@jskit-ai/feature-server-generator 0.1.1

package/package.descriptor.mjs

@@ -0,0 +1,268 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/feature-server-generator",
+  version: "0.1.1",
+  kind: "generator",
+  description: "Scaffold substantial non-CRUD server feature packages with provider, actions, service, and optional persistence seams.",
+  options: {
+    "feature-name": {
+      required: true,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Feature name",
+      promptHint: "Required feature slug (example: booking-engine, availability-engine, billing-engine)."
+    },
+    mode: {
+      required: false,
+      inputType: "text",
+      defaultValue: "json-rest",
+      validationType: "enum",
+      allowedValues: ["json-rest", "orchestrator", "custom-knex"],
+      promptLabel: "Scaffold mode",
+      promptHint: "json-rest | orchestrator | custom-knex"
+    },
+    surface: {
+      required: false,
+      inputType: "text",
+      validationType: "enabled-surface-id",
+      promptLabel: "Target surface",
+      promptHint: "Optional surface id for generated action and route metadata."
+    },
+    "route-prefix": {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Route prefix",
+      promptHint: "Optional relative API path (example: admin/booking-engine)."
+    },
+    force: {
+      required: false,
+      inputType: "flag",
+      defaultValue: "",
+      promptLabel: "Force overwrite",
+      promptHint: "Overwrite generated scaffold files if the feature package directory already exists."
+    }
+  },
+  dependsOn: [],
+  capabilities: {
+    provides: ["feature-server-generator"],
+    requires: []
+  },
+  runtime: {
+    server: {
+      providers: []
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    generatorPrimarySubcommand: "scaffold",
+    generatorSubcommands: {
+      scaffold: {
+        description: "Create a dedicated non-CRUD server feature package with provider, actions, service, and optional repository/routes.",
+        longDescription: [
+          "This is the standard JSKIT starting point for substantial non-CRUD server features such as engines, workflows, and policy services.",
+          "The default mode is json-rest. Use orchestrator for non-persistent coordination packages, or custom-knex only when raw knex is an explicit exception."
+        ],
+        positionalArgs: [
+          {
+            name: "feature-name",
+            required: true,
+            description: "Feature slug used for the package path, provider name, inline action ids, and default container tokens."
+          }
+        ],
+        optionNames: ["feature-name", "mode", "surface", "route-prefix", "force"],
+        createTarget: {
+          pathTemplate: "packages/${option:feature-name|kebab}",
+          label: "package directory",
+          allowExistingEmptyDirectory: false
+        },
+        notes: [
+          "json-rest emits a repository that starts from internal json-rest-api seams.",
+          "orchestrator omits repository.js entirely and keeps the service focused on coordination.",
+          "custom-knex is the explicit weird/custom lane and emits a repository wired to jskit.database.knex.",
+          "If --route-prefix is omitted, registerRoutes.js is not generated."
+        ],
+        examples: [
+          {
+            label: "Default persistent feature",
+            lines: [
+              "npx jskit generate feature-server-generator scaffold \\",
+              "  booking-engine"
+            ]
+          },
+          {
+            label: "Non-persistent orchestrator",
+            lines: [
+              "npx jskit generate feature-server-generator scaffold \\",
+              "  availability-engine \\",
+              "  --mode orchestrator"
+            ]
+          },
+          {
+            label: "Another default persistent feature",
+            lines: [
+              "npx jskit generate feature-server-generator scaffold \\",
+              "  billing-engine"
+            ]
+          },
+          {
+            label: "Rare explicit custom-knex feature",
+            lines: [
+              "npx jskit generate feature-server-generator scaffold \\",
+              "  invoice-rollup \\",
+              "  --mode custom-knex \\",
+              "  --route-prefix admin/invoice-rollup \\",
+              "  --surface admin"
+            ]
+          }
+        ]
+      }
+    },
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/buildTemplateContext",
+          summary: "Builds deterministic non-CRUD feature server scaffold template context values."
+        }
+      ],
+      containerTokens: {
+        server: [],
+        client: []
+      }
+    },
+    jskit: {
+      ownershipGuidance: {
+        title: "Standard non-CRUD server lane",
+        summary: "Use this generator when a substantial server feature should become its own package instead of growing inside packages/main.",
+        responsibilities: [
+          "provider: wires DI, actions, repository, and optional routes",
+          "service: owns orchestration and must not talk to persistence directly",
+          "repository: owns persistence; default-lane persistent scaffolds start from internal json-rest-api",
+          "packages/main: stays composition/glue only"
+        ],
+        examples: [
+          "jskit generate feature-server-generator scaffold booking-engine",
+          "jskit generate feature-server-generator scaffold availability-engine --mode orchestrator",
+          "jskit generate feature-server-generator scaffold billing-engine"
+        ]
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/database-runtime": "0.1.59",
+        "@jskit-ai/database-runtime-mysql": "0.1.58",
+        "@jskit-ai/json-rest-api-core": "0.1.4",
+        "@jskit-ai/kernel": "0.1.59",
+        "json-rest-schema": "1.x.x",
+        "@local/${option:feature-name|kebab}": "file:packages/${option:feature-name|kebab}"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [
+      {
+        from: "templates/src/local-package/package.json",
+        to: "packages/${option:feature-name|kebab}/package.json",
+        reason: "Install app-local non-CRUD feature package manifest.",
+        category: "feature-server-generator",
+        id: "feature-server-package-json-${option:feature-name|snake}"
+      },
+      {
+        from: "templates/src/local-package/package.descriptor.mjs",
+        to: "packages/${option:feature-name|kebab}/package.descriptor.mjs",
+        reason: "Install app-local non-CRUD feature package descriptor.",
+        category: "feature-server-generator",
+        id: "feature-server-package-descriptor-${option:feature-name|snake}",
+        templateContext: {
+          entrypoint: "src/server/buildTemplateContext.js",
+          export: "buildTemplateContext"
+        }
+      },
+      {
+        from: "templates/src/local-package/server/FeatureProvider.js",
+        to: "packages/${option:feature-name|kebab}/src/server/${option:feature-name|pascal}Provider.js",
+        reason: "Install app-local non-CRUD feature provider.",
+        category: "feature-server-generator",
+        id: "feature-server-provider-${option:feature-name|snake}",
+        templateContext: {
+          entrypoint: "src/server/buildTemplateContext.js",
+          export: "buildTemplateContext"
+        }
+      },
+      {
+        from: "templates/src/local-package/server/inputSchemas.js",
+        to: "packages/${option:feature-name|kebab}/src/server/inputSchemas.js",
+        reason: "Install generated feature action and route validators.",
+        category: "feature-server-generator",
+        id: "feature-server-input-schemas-${option:feature-name|snake}"
+      },
+      {
+        from: "templates/src/local-package/server/actions.js",
+        to: "packages/${option:feature-name|kebab}/src/server/actions.js",
+        reason: "Install generated feature action definitions.",
+        category: "feature-server-generator",
+        id: "feature-server-actions-${option:feature-name|snake}",
+        templateContext: {
+          entrypoint: "src/server/buildTemplateContext.js",
+          export: "buildTemplateContext"
+        }
+      },
+      {
+        from: "templates/src/local-package/server/service.js",
+        to: "packages/${option:feature-name|kebab}/src/server/service.js",
+        reason: "Install generated feature service.",
+        category: "feature-server-generator",
+        id: "feature-server-service-${option:feature-name|snake}",
+        templateContext: {
+          entrypoint: "src/server/buildTemplateContext.js",
+          export: "buildTemplateContext"
+        }
+      },
+      {
+        from: "templates/src/local-package/server/registerRoutes.js",
+        to: "packages/${option:feature-name|kebab}/src/server/registerRoutes.js",
+        reason: "Install generated feature route registration.",
+        category: "feature-server-generator",
+        id: "feature-server-routes-${option:feature-name|snake}",
+        templateContext: {
+          entrypoint: "src/server/buildTemplateContext.js",
+          export: "buildTemplateContext"
+        },
+        when: {
+          option: "route-prefix",
+          hasText: true
+        }
+      },
+      {
+        from: "templates/src/local-package/server/repositoryJsonRest.js",
+        to: "packages/${option:feature-name|kebab}/src/server/repository.js",
+        reason: "Install generated feature repository with internal json-rest-api seam.",
+        category: "feature-server-generator",
+        id: "feature-server-repository-json-rest-${option:feature-name|snake}",
+        when: {
+          option: "mode",
+          equals: "json-rest"
+        }
+      },
+      {
+        from: "templates/src/local-package/server/repositoryCustomKnex.js",
+        to: "packages/${option:feature-name|kebab}/src/server/repository.js",
+        reason: "Install generated feature repository with explicit knex seam.",
+        category: "feature-server-generator",
+        id: "feature-server-repository-custom-knex-${option:feature-name|snake}",
+        when: {
+          option: "mode",
+          equals: "custom-knex"
+        }
+      }
+    ],
+    text: []
+  }
+});

package/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@jskit-ai/feature-server-generator",
+  "version": "0.1.1",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/server/buildTemplateContext.js

@@ -0,0 +1,274 @@
+function splitTextIntoWords(value) {
+  const normalized = String(value || "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim();
+  if (!normalized) {
+    return [];
+  }
+
+  return normalized
+    .split(/\s+/u)
+    .map((entry) => String(entry || "").trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function wordsToPascal(words = []) {
+  return words
+    .map((entry) => {
+      const value = String(entry || "").trim().toLowerCase();
+      if (!value) {
+        return "";
+      }
+      return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+    })
+    .join("");
+}
+
+function wordsToKebab(words = []) {
+  return words
+    .map((entry) => String(entry || "").trim().toLowerCase())
+    .filter(Boolean)
+    .join("-");
+}
+
+function wordsToCamel(words = []) {
+  const pascal = wordsToPascal(words);
+  if (!pascal) {
+    return "";
+  }
+  return `${pascal.slice(0, 1).toLowerCase()}${pascal.slice(1)}`;
+}
+
+function normalizeFeatureName(value) {
+  const normalized = wordsToKebab(splitTextIntoWords(value));
+  if (!normalized) {
+    throw new Error("feature-server-generator requires option feature-name.");
+  }
+  return normalized;
+}
+
+function normalizeSurfaceId(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function normalizeRoutePrefix(value) {
+  return String(value || "")
+    .split("/")
+    .map((segment) => {
+      const normalizedSegment = String(segment || "").trim();
+      if (!normalizedSegment) {
+        return "";
+      }
+      if (normalizedSegment.startsWith(":")) {
+        return normalizedSegment;
+      }
+      return wordsToKebab(splitTextIntoWords(normalizedSegment));
+    })
+    .filter(Boolean)
+    .join("/");
+}
+
+function quoteArray(values = []) {
+  return values.map((entry) => JSON.stringify(String(entry || ""))).join(", ");
+}
+
+function buildProviderContext({ featureName, mode, routePrefix, surface }) {
+  const featureToken = `feature.${featureName}`;
+  const isJsonRest = mode === "json-rest";
+  const isCustomKnex = mode === "custom-knex";
+  const hasRoutes = Boolean(routePrefix);
+
+  const dependsOn = ["runtime.actions"];
+  if (isJsonRest) {
+    dependsOn.push("json-rest-api.core");
+  }
+  if (isCustomKnex) {
+    dependsOn.push("runtime.database");
+  }
+
+  let repositoryImport = "";
+  let repositoryRegistration = "";
+  let serviceFactoryArg = "{}";
+  if (isJsonRest) {
+    repositoryImport = [
+      'import { INTERNAL_JSON_REST_API } from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";',
+      'import { createRepository } from "./repository.js";'
+    ].join("\n");
+    repositoryRegistration = [
+      `    app.singleton("${featureToken}.repository", (scope) => {`,
+      "      return createRepository({",
+      "        api: scope.make(INTERNAL_JSON_REST_API)",
+      "      });",
+      "    });",
+      ""
+    ].join("\n");
+    serviceFactoryArg = `{ featureRepository: _scope.make("${featureToken}.repository") }`;
+  } else if (isCustomKnex) {
+    repositoryImport = 'import { createRepository } from "./repository.js";';
+    repositoryRegistration = [
+      `    app.singleton("${featureToken}.repository", (scope) => {`,
+      "      return createRepository({",
+      '        knex: scope.make("jskit.database.knex")',
+      "      });",
+      "    });",
+      ""
+    ].join("\n");
+    serviceFactoryArg = `{ featureRepository: _scope.make("${featureToken}.repository") }`;
+  }
+
+  let routeImport = "";
+  let bootMethod = "  boot() {}";
+  if (hasRoutes) {
+    const routeLines = [
+      "  boot(app) {",
+      "    registerRoutes(app, {",
+      `      routeRelativePath: ${JSON.stringify(routePrefix)},`
+    ];
+    if (surface) {
+      routeLines.push(`      routeSurface: ${JSON.stringify(surface)}`);
+    }
+    routeLines.push("    });");
+    routeLines.push("  }");
+    routeImport = 'import { registerRoutes } from "./registerRoutes.js";';
+    bootMethod = routeLines.join("\n");
+  }
+
+  return Object.freeze({
+    "__JSKIT_FEATURE_PROVIDER_DEPENDS_ON__": quoteArray(dependsOn),
+    "__JSKIT_FEATURE_PROVIDER_REPOSITORY_IMPORT__": repositoryImport,
+    "__JSKIT_FEATURE_PROVIDER_ROUTE_IMPORT__": routeImport,
+    "__JSKIT_FEATURE_PROVIDER_REPOSITORY_REGISTRATION__": repositoryRegistration,
+    "__JSKIT_FEATURE_PROVIDER_SERVICE_FACTORY_ARG__": serviceFactoryArg,
+    "__JSKIT_FEATURE_PROVIDER_BOOT_METHOD__": bootMethod
+  });
+}
+
+function buildActionsContext({ surface }) {
+  const surfacesLine = surface
+    ? `    surfaces: [${JSON.stringify(surface)}],`
+    : '    surfacesFrom: "enabled",';
+
+  return Object.freeze({
+    "__JSKIT_FEATURE_ACTION_SURFACES_LINE__": surfacesLine
+  });
+}
+
+function buildServiceContext({ featureName, mode }) {
+  const featureToken = `feature.${featureName}`;
+  const isPersistent = mode === "json-rest" || mode === "custom-knex";
+  if (!isPersistent) {
+    return Object.freeze({
+      "__JSKIT_FEATURE_SERVICE_REPOSITORY_GUARD__": "  void featureRepository;",
+      "__JSKIT_FEATURE_SERVICE_GET_STATUS_BODY__": [
+        "      void options;",
+        "      return {",
+        `        ok: true,`,
+        `        feature: ${JSON.stringify(featureName)},`,
+        `        mode: ${JSON.stringify(mode)},`,
+        "        customized: false,",
+        "        input,",
+        '        message: "Replace createService().getStatus() with feature-specific orchestration logic."',
+        "      };"
+      ].join("\n"),
+      "__JSKIT_FEATURE_SERVICE_EXECUTE_BODY__": [
+        "      void options;",
+        "      return {",
+        "        accepted: false,",
+        `        feature: ${JSON.stringify(featureName)},`,
+        `        mode: ${JSON.stringify(mode)},`,
+        "        customized: false,",
+        "        input,",
+        '        message: "Replace createService().execute() with feature-specific orchestration logic."',
+        "      };"
+      ].join("\n")
+    });
+  }
+
+  return Object.freeze({
+    "__JSKIT_FEATURE_SERVICE_REPOSITORY_GUARD__": [
+      "  if (!featureRepository) {",
+      `    throw new TypeError("createService requires ${featureToken}.repository.");`,
+      "  }"
+    ].join("\n"),
+    "__JSKIT_FEATURE_SERVICE_GET_STATUS_BODY__": [
+      "      return featureRepository.getStatus(input, {",
+      "        context: options?.context || null",
+      "      });"
+    ].join("\n"),
+    "__JSKIT_FEATURE_SERVICE_EXECUTE_BODY__": [
+      "      return featureRepository.execute(input, {",
+      "        context: options?.context || null,",
+      "        trx: options?.trx || null",
+      "      });"
+    ].join("\n")
+  });
+}
+
+function buildRouteContext({ surface }) {
+  const routeSurfaceImport = surface ? ", normalizeSurfaceId" : "";
+  const routeSurfaceNormalizerLine = surface
+    ? "  const normalizedRouteSurface = normalizeSurfaceId(routeSurface);"
+    : "  void routeSurface;";
+  const routeSurfaceLine = surface ? "      surface: normalizedRouteSurface," : "";
+
+  return Object.freeze({
+    "__JSKIT_FEATURE_ROUTE_SURFACE_IMPORT__": routeSurfaceImport,
+    "__JSKIT_FEATURE_ROUTE_SURFACE_NORMALIZER_LINE__": routeSurfaceNormalizerLine,
+    "__JSKIT_FEATURE_ROUTE_SURFACE_LINE__": routeSurfaceLine
+  });
+}
+
+function buildDescriptorContext({ featureName, mode }) {
+  const isJsonRest = mode === "json-rest";
+  const isCustomKnex = mode === "custom-knex";
+  const isPersistent = isJsonRest || isCustomKnex;
+  const dependsOnLines = [];
+  if (isJsonRest) {
+    dependsOnLines.push('    "@jskit-ai/json-rest-api-core"');
+  }
+  if (isCustomKnex) {
+    dependsOnLines.push('    "@jskit-ai/database-runtime"');
+  }
+
+  const descriptorDependsOnLines = dependsOnLines.length > 0
+    ? `,\n${dependsOnLines.join(",\n")}`
+    : "";
+  const descriptorRepositoryTokenLine = isPersistent ? `,\n          "feature.${featureName}.repository"` : "";
+  const lane = isCustomKnex ? "weird-custom" : "default";
+
+  return Object.freeze({
+    "__JSKIT_FEATURE_DESCRIPTOR_DEPENDS_ON_LINES__": descriptorDependsOnLines,
+    "__JSKIT_FEATURE_DESCRIPTOR_CAPABILITY_REQUIRES_LINES__": "",
+    "__JSKIT_FEATURE_DESCRIPTOR_REPOSITORY_TOKEN_LINE__": descriptorRepositoryTokenLine,
+    "__JSKIT_FEATURE_DESCRIPTOR_LANE__": lane
+  });
+}
+
+async function buildTemplateContext({ options = {} } = {}) {
+  const featureName = normalizeFeatureName(options["feature-name"]);
+  const mode = String(options.mode || "json-rest").trim() || "json-rest";
+  const routePrefix = normalizeRoutePrefix(options["route-prefix"]);
+  const surface = normalizeSurfaceId(options.surface);
+  const context = {
+    "__JSKIT_FEATURE_NAME_KEBAB__": featureName,
+    "__JSKIT_FEATURE_NAME_PASCAL__": wordsToPascal(splitTextIntoWords(featureName)),
+    "__JSKIT_FEATURE_NAME_CAMEL__": wordsToCamel(splitTextIntoWords(featureName))
+  };
+
+  return Object.freeze({
+    ...context,
+    ...buildProviderContext({
+      featureName,
+      mode,
+      routePrefix,
+      surface
+    }),
+    ...buildActionsContext({ surface }),
+    ...buildServiceContext({ featureName, mode }),
+    ...buildRouteContext({ surface }),
+    ...buildDescriptorContext({ featureName, mode })
+  });
+}
+
+export { buildTemplateContext };

package/templates/src/local-package/package.descriptor.mjs

@@ -0,0 +1,64 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@local/${option:feature-name|kebab}",
+  version: "0.1.0",
+  kind: "runtime",
+  description: "App-local non-CRUD feature package (${option:feature-name|kebab}).",
+  dependsOn: [
+    "@jskit-ai/kernel"__JSKIT_FEATURE_DESCRIPTOR_DEPENDS_ON_LINES__
+  ],
+  capabilities: {
+    provides: [
+      "feature.${option:feature-name|kebab}"
+    ],
+    requires: [
+      "runtime.actions"__JSKIT_FEATURE_DESCRIPTOR_CAPABILITY_REQUIRES_LINES__
+    ]
+  },
+  runtime: {
+    server: {
+      providers: [
+        {
+          entrypoint: "src/server/${option:feature-name|pascal}Provider.js",
+          export: "${option:feature-name|pascal}Provider"
+        }
+      ]
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/actions",
+          summary: "Exports generated feature action definitions with inline starter ids."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "feature.${option:feature-name|kebab}.service"__JSKIT_FEATURE_DESCRIPTOR_REPOSITORY_TOKEN_LINE__
+        ],
+        client: []
+      }
+    },
+    jskit: {
+      scaffoldShape: "feature-server-v1",
+      scaffoldMode: "${option:mode}",
+      lane: "__JSKIT_FEATURE_DESCRIPTOR_LANE__"
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {},
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [],
+    text: []
+  }
+});

package/templates/src/local-package/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@local/${option:feature-name|kebab}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./server/actions": "./src/server/actions.js"
+  }
+}

package/templates/src/local-package/server/FeatureProvider.js

@@ -0,0 +1,43 @@
+import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+__JSKIT_FEATURE_PROVIDER_REPOSITORY_IMPORT__
+import { createService } from "./service.js";
+import { featureActions } from "./actions.js";
+__JSKIT_FEATURE_PROVIDER_ROUTE_IMPORT__
+
+class ${option:feature-name|pascal}Provider {
+  static id = "feature.${option:feature-name|kebab}";
+
+  static dependsOn = [__JSKIT_FEATURE_PROVIDER_DEPENDS_ON__];
+
+  register(app) {
+    if (
+      !app ||
+      typeof app.singleton !== "function" ||
+      typeof app.service !== "function" ||
+      typeof app.actions !== "function"
+    ) {
+      throw new Error("${option:feature-name|pascal}Provider requires application singleton()/service()/actions().");
+    }
+
+__JSKIT_FEATURE_PROVIDER_REPOSITORY_REGISTRATION__
+    app.service(
+      "feature.${option:feature-name|kebab}.service",
+      (_scope) => {
+        return createService(__JSKIT_FEATURE_PROVIDER_SERVICE_FACTORY_ARG__);
+      }
+    );
+
+    app.actions(
+      withActionDefaults(featureActions, {
+        domain: "feature",
+        dependencies: {
+          featureService: "feature.${option:feature-name|kebab}.service"
+        }
+      })
+    );
+  }
+
+__JSKIT_FEATURE_PROVIDER_BOOT_METHOD__
+}
+
+export { ${option:feature-name|pascal}Provider };

package/templates/src/local-package/server/actions.js

@@ -0,0 +1,50 @@
+import {
+  statusQueryInputValidator,
+  executeCommandInputValidator
+} from "./inputSchemas.js";
+
+const ACTION_GET_STATUS = "feature.${option:feature-name|kebab}.status.read";
+const ACTION_EXECUTE = "feature.${option:feature-name|kebab}.execute";
+
+const featureActions = Object.freeze([
+  {
+    id: ACTION_GET_STATUS,
+    version: 1,
+    kind: "query",
+    channels: ["api", "automation", "internal"],
+__JSKIT_FEATURE_ACTION_SURFACES_LINE__
+    input: statusQueryInputValidator,
+    output: null,
+    idempotency: "none",
+    audit: {
+      actionName: ACTION_GET_STATUS
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.featureService.getStatus(input, {
+        context
+      });
+    }
+  },
+  {
+    id: ACTION_EXECUTE,
+    version: 1,
+    kind: "command",
+    channels: ["api", "automation", "internal"],
+__JSKIT_FEATURE_ACTION_SURFACES_LINE__
+    input: executeCommandInputValidator,
+    output: null,
+    idempotency: "optional",
+    audit: {
+      actionName: ACTION_EXECUTE
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.featureService.execute(input, {
+        context
+      });
+    }
+  }
+]);
+
+export { featureActions };

package/templates/src/local-package/server/inputSchemas.js

@@ -0,0 +1,38 @@
+import { createSchema } from "json-rest-schema";
+import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
+
+const statusQueryInputValidator = deepFreeze({
+  schema: createSchema({
+    scope: {
+      type: "string",
+      required: false,
+      minLength: 1
+    },
+    verbose: {
+      type: "boolean",
+      required: false
+    }
+  }),
+  mode: "patch"
+});
+
+const executeCommandInputValidator = deepFreeze({
+  schema: createSchema({
+    command: {
+      type: "string",
+      required: true,
+      minLength: 1
+    },
+    payload: {
+      type: "object",
+      required: false,
+      additionalProperties: true
+    }
+  }),
+  mode: "patch"
+});
+
+export {
+  statusQueryInputValidator,
+  executeCommandInputValidator
+};

package/templates/src/local-package/server/registerRoutes.js

@@ -0,0 +1,74 @@
+import { resolveScopedApiBasePath__JSKIT_FEATURE_ROUTE_SURFACE_IMPORT__ } from "@jskit-ai/kernel/shared/surface";
+import {
+  statusQueryInputValidator,
+  executeCommandInputValidator
+} from "./inputSchemas.js";
+
+const ACTION_GET_STATUS = "feature.${option:feature-name|kebab}.status.read";
+const ACTION_EXECUTE = "feature.${option:feature-name|kebab}.execute";
+
+function registerRoutes(
+  app,
+  {
+    routeSurface = "",
+    routeRelativePath = ""
+  } = {}
+) {
+  if (!app || typeof app.make !== "function") {
+    throw new Error("registerRoutes requires application make().");
+  }
+
+  const router = app.make("jskit.http.router");
+__JSKIT_FEATURE_ROUTE_SURFACE_NORMALIZER_LINE__
+  const routeBase = resolveScopedApiBasePath({
+    routeBase: "/",
+    relativePath: routeRelativePath,
+    strictParams: false
+  });
+
+  router.register(
+    "GET",
+    routeBase,
+    {
+      auth: "public",
+__JSKIT_FEATURE_ROUTE_SURFACE_LINE__
+      meta: {
+        tags: ["feature"],
+        summary: "Read feature status."
+      },
+      query: statusQueryInputValidator
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: ACTION_GET_STATUS,
+        input: request.input.query || {}
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "POST",
+    routeBase,
+    {
+      auth: "public",
+__JSKIT_FEATURE_ROUTE_SURFACE_LINE__
+      meta: {
+        tags: ["feature"],
+        summary: "Execute feature command."
+      },
+      body: executeCommandInputValidator
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: ACTION_EXECUTE,
+        input: request.input.body || {}
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { registerRoutes };

package/templates/src/local-package/server/repositoryCustomKnex.js

@@ -0,0 +1,39 @@
+import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
+
+const FEATURE_TABLE_NAME = "${option:feature-name|snake}";
+const FEATURE_NAME = "${option:feature-name|kebab}";
+
+function createRepository({ knex } = {}) {
+  if (!knex) {
+    throw new TypeError("createRepository requires knex.");
+  }
+
+  const withTransaction = createWithTransaction(knex);
+
+  return Object.freeze({
+    withTransaction,
+    async getStatus(input = {}, options = {}) {
+      return {
+        ok: true,
+        feature: FEATURE_NAME,
+        persistence: "custom-knex",
+        tableName: FEATURE_TABLE_NAME,
+        hasTransaction: Boolean(options?.trx),
+        input
+      };
+    },
+    async execute(input = {}, options = {}) {
+      return {
+        accepted: false,
+        feature: FEATURE_NAME,
+        persistence: "custom-knex",
+        tableName: FEATURE_TABLE_NAME,
+        hasTransaction: Boolean(options?.trx),
+        input,
+        message: "Customize repository.execute() with explicit knex queries."
+      };
+    }
+  });
+}
+
+export { createRepository };

package/templates/src/local-package/server/repositoryJsonRest.js

@@ -0,0 +1,44 @@
+import { createJsonRestContext } from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
+
+const FEATURE_RESOURCE_KEY = "${option:feature-name|camel}";
+const FEATURE_RESOURCE_TYPE = "${option:feature-name|kebab}";
+
+function createRepository({ api } = {}) {
+  if (!api) {
+    throw new TypeError("createRepository requires api.");
+  }
+
+  return Object.freeze({
+    async getStatus(input = {}, options = {}) {
+      const jsonRestContext = createJsonRestContext(options?.context || null);
+      const featureResource = api?.resources?.[FEATURE_RESOURCE_KEY] || null;
+
+      return {
+        ok: true,
+        feature: FEATURE_RESOURCE_TYPE,
+        persistence: "json-rest",
+        resourceKey: FEATURE_RESOURCE_KEY,
+        resourceAvailable: Boolean(featureResource),
+        hasContext: Boolean(jsonRestContext),
+        input
+      };
+    },
+    async execute(input = {}, options = {}) {
+      const jsonRestContext = createJsonRestContext(options?.context || null);
+      const featureResource = api?.resources?.[FEATURE_RESOURCE_KEY] || null;
+
+      return {
+        accepted: false,
+        feature: FEATURE_RESOURCE_TYPE,
+        persistence: "json-rest",
+        resourceKey: FEATURE_RESOURCE_KEY,
+        resourceAvailable: Boolean(featureResource),
+        hasContext: Boolean(jsonRestContext),
+        input,
+        message: "Customize repository.execute() to read and write through internal json-rest-api."
+      };
+    }
+  });
+}
+
+export { createRepository };

package/templates/src/local-package/server/service.js

@@ -0,0 +1,14 @@
+function createService({ featureRepository } = {}) {
+__JSKIT_FEATURE_SERVICE_REPOSITORY_GUARD__
+
+  return Object.freeze({
+    async getStatus(input = {}, options = {}) {
+__JSKIT_FEATURE_SERVICE_GET_STATUS_BODY__
+    },
+    async execute(input = {}, options = {}) {
+__JSKIT_FEATURE_SERVICE_EXECUTE_BODY__
+    }
+  });
+}
+
+export { createService };

package/test/buildTemplateContext.test.js

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildTemplateContext } from "../src/server/buildTemplateContext.js";
+
+test("buildTemplateContext emits json-rest provider and descriptor wiring", async () => {
+  const context = await buildTemplateContext({
+    options: {
+      "feature-name": "Booking Engine",
+      mode: "json-rest"
+    }
+  });
+
+  assert.equal(context.__JSKIT_FEATURE_PROVIDER_DEPENDS_ON__, '"runtime.actions", "json-rest-api.core"');
+  assert.match(context.__JSKIT_FEATURE_PROVIDER_REPOSITORY_IMPORT__, /INTERNAL_JSON_REST_API/);
+  assert.match(context.__JSKIT_FEATURE_PROVIDER_REPOSITORY_REGISTRATION__, /feature\.booking-engine\.repository/);
+  assert.equal(
+    context.__JSKIT_FEATURE_PROVIDER_SERVICE_FACTORY_ARG__,
+    '{ featureRepository: _scope.make("feature.booking-engine.repository") }'
+  );
+  assert.equal(context.__JSKIT_FEATURE_PROVIDER_BOOT_METHOD__, "  boot() {}");
+  assert.match(context.__JSKIT_FEATURE_DESCRIPTOR_DEPENDS_ON_LINES__, /@jskit-ai\/json-rest-api-core/);
+  assert.equal(context.__JSKIT_FEATURE_DESCRIPTOR_CAPABILITY_REQUIRES_LINES__, "");
+  assert.equal(context.__JSKIT_FEATURE_DESCRIPTOR_LANE__, "default");
+});
+
+test("buildTemplateContext emits orchestrator service placeholders and enabled-surface actions", async () => {
+  const context = await buildTemplateContext({
+    options: {
+      "feature-name": "Availability Engine",
+      mode: "orchestrator"
+    }
+  });
+
+  assert.equal(context.__JSKIT_FEATURE_PROVIDER_DEPENDS_ON__, '"runtime.actions"');
+  assert.equal(context.__JSKIT_FEATURE_PROVIDER_REPOSITORY_IMPORT__, "");
+  assert.equal(context.__JSKIT_FEATURE_PROVIDER_REPOSITORY_REGISTRATION__, "");
+  assert.equal(context.__JSKIT_FEATURE_PROVIDER_SERVICE_FACTORY_ARG__, "{}");
+  assert.equal(context.__JSKIT_FEATURE_ACTION_SURFACES_LINE__, '    surfacesFrom: "enabled",');
+  assert.match(context.__JSKIT_FEATURE_SERVICE_GET_STATUS_BODY__, /orchestration logic/);
+  assert.equal(context.__JSKIT_FEATURE_DESCRIPTOR_REPOSITORY_TOKEN_LINE__, "");
+});
+
+test("buildTemplateContext emits custom-knex route wiring and weird-custom lane metadata", async () => {
+  const context = await buildTemplateContext({
+    options: {
+      "feature-name": "Invoice Rollup",
+      mode: "custom-knex",
+      surface: "ADMIN",
+      "route-prefix": "Admin/Invoice Rollup"
+    }
+  });
+
+  assert.equal(context.__JSKIT_FEATURE_PROVIDER_DEPENDS_ON__, '"runtime.actions", "runtime.database"');
+  assert.match(context.__JSKIT_FEATURE_PROVIDER_REPOSITORY_IMPORT__, /createRepository/);
+  assert.match(context.__JSKIT_FEATURE_PROVIDER_BOOT_METHOD__, /routeRelativePath: "admin\/invoice-rollup"/);
+  assert.match(context.__JSKIT_FEATURE_PROVIDER_BOOT_METHOD__, /routeSurface: "admin"/);
+  assert.equal(context.__JSKIT_FEATURE_ACTION_SURFACES_LINE__, '    surfaces: ["admin"],');
+  assert.equal(context.__JSKIT_FEATURE_ROUTE_SURFACE_IMPORT__, ", normalizeSurfaceId");
+  assert.equal(context.__JSKIT_FEATURE_ROUTE_SURFACE_LINE__, "      surface: normalizedRouteSurface,");
+  assert.equal(context.__JSKIT_FEATURE_DESCRIPTOR_LANE__, "weird-custom");
+  assert.equal(context.__JSKIT_FEATURE_DESCRIPTOR_CAPABILITY_REQUIRES_LINES__, "");
+});

package/test/packageDescriptor.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import descriptor from "../package.descriptor.mjs";
+
+test("feature-server-generator exposes the scaffold primary subcommand contract", () => {
+  assert.equal(descriptor.kind, "generator");
+  assert.equal(descriptor.options?.mode?.validationType, "enum");
+  assert.deepEqual(
+    descriptor.options?.mode?.allowedValues,
+    ["json-rest", "orchestrator", "custom-knex"]
+  );
+  assert.equal(descriptor.options?.surface?.validationType, "enabled-surface-id");
+  assert.equal(descriptor.metadata?.generatorPrimarySubcommand, "scaffold");
+  assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.createTarget?.pathTemplate, "packages/${option:feature-name|kebab}");
+  assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.optionNames?.includes("feature-name"), true);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.optionNames?.includes("route-prefix"), true);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.optionNames?.includes("force"), true);
+});
+
+test("feature-server-generator routes mode-specific files through mutation when clauses", () => {
+  const files = descriptor.mutations?.files || [];
+  const routesTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/registerRoutes.js");
+  const jsonRestRepositoryTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/repositoryJsonRest.js");
+  const customKnexRepositoryTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/repositoryCustomKnex.js");
+  const providerTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/FeatureProvider.js");
+  const actionIdsTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/actionIds.js");
+
+  assert.ok(routesTemplate);
+  assert.deepEqual(routesTemplate.when, {
+    option: "route-prefix",
+    hasText: true
+  });
+
+  assert.ok(jsonRestRepositoryTemplate);
+  assert.deepEqual(jsonRestRepositoryTemplate.when, {
+    option: "mode",
+    equals: "json-rest"
+  });
+
+  assert.ok(customKnexRepositoryTemplate);
+  assert.deepEqual(customKnexRepositoryTemplate.when, {
+    option: "mode",
+    equals: "custom-knex"
+  });
+
+  assert.ok(providerTemplate);
+  assert.deepEqual(providerTemplate.templateContext, {
+    entrypoint: "src/server/buildTemplateContext.js",
+    export: "buildTemplateContext"
+  });
+
+  assert.equal(actionIdsTemplate, undefined);
+});