@wneng/create-keel 0.1.2 → 0.2.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/version.ts
-var SCAFFOLDER_VERSION = "0.1.2";
+var SCAFFOLDER_VERSION = "0.2.0";
 
 // src/schema/options.ts
 import Ajv from "ajv";
@@ -151,6 +151,189 @@ function formatError(err) {
   \u5EFA\u8BAE\uFF1A\u8BF7\u5728 issue \u4E2D\u9644\u4E0A\u5B8C\u6574\u4E0A\u4E0B\u6587`;
 }
 
+// src/feature/layers.ts
+var FEATURE_LAYERS = ["pm", "arch", "backend", "frontend", "test"];
+var FEATURE_SLUG_PATTERN = PROJECT_NAME_PATTERN;
+var FEATURE_SLUG_PATTERN_SOURCE = "^[a-z0-9][a-z0-9-]{0,62}$";
+function isValidFeatureSlug(value) {
+  return FEATURE_SLUG_PATTERN.test(value);
+}
+function isFeatureLayer(value) {
+  return FEATURE_LAYERS.includes(value);
+}
+var LAYER_ARTIFACTS = {
+  pm: {
+    layer: "pm",
+    label: "PRD (docs/01-\u80CC\u666F\u4E0E\u9700\u6C42)",
+    placeholderTemplate: "pm/prd.md.eta",
+    outputPath: (slug) => `docs/01-\u80CC\u666F\u4E0E\u9700\u6C42/prd-${slug}.md`
+  },
+  arch: {
+    layer: "arch",
+    label: "ADR (docs/02-\u7CFB\u7EDF\u65B9\u6848\u4E0E\u67B6\u6784)",
+    placeholderTemplate: "arch/adr.md.eta",
+    // ADR file names also embed a 4-digit sequence number; the planner
+    // resolves that prefix at scaffold time and prepends it. The slug-only
+    // suffix is what this function returns; callers that need the full
+    // path must compose the prefix.
+    outputPath: (slug) => `docs/02-\u7CFB\u7EDF\u65B9\u6848\u4E0E\u67B6\u6784/adr-${slug}.md`
+  },
+  backend: {
+    layer: "backend",
+    label: "backend design (docs/04-\u540E\u7AEF\u8BE6\u7EC6\u8BBE\u8BA1)",
+    placeholderTemplate: "backend/design.md.eta",
+    outputPath: (slug) => `docs/04-\u540E\u7AEF\u8BE6\u7EC6\u8BBE\u8BA1/${slug}.md`
+  },
+  frontend: {
+    layer: "frontend",
+    label: "frontend design (docs/05-\u524D\u7AEF\u5BA2\u6237\u7AEF\u8BE6\u7EC6\u8BBE\u8BA1)",
+    placeholderTemplate: "frontend/design.md.eta",
+    outputPath: (slug) => `docs/05-\u524D\u7AEF\u5BA2\u6237\u7AEF\u8BE6\u7EC6\u8BBE\u8BA1/${slug}-web.md`
+  },
+  test: {
+    layer: "test",
+    label: "test plan (docs/07-\u8D28\u91CF\u4E0E\u6D4B\u8BD5/test-plans)",
+    placeholderTemplate: "test/test-plan.md.eta",
+    outputPath: (slug) => `docs/07-\u8D28\u91CF\u4E0E\u6D4B\u8BD5/test-plans/${slug}.md`
+  }
+};
+var LAYER_REQUIRED_ROLE = {
+  test: "qa"
+};
+function layerEnabledByRoles(layer, roles) {
+  const required = LAYER_REQUIRED_ROLE[layer];
+  if (required === void 0) return true;
+  return roles.includes(required);
+}
+function resolveLayers(requested, roles) {
+  const requestedSet = requested === void 0 || requested === "all" ? new Set(FEATURE_LAYERS) : new Set(requested);
+  const out = [];
+  for (const layer of FEATURE_LAYERS) {
+    if (!requestedSet.has(layer)) continue;
+    if (!layerEnabledByRoles(layer, roles)) continue;
+    out.push(layer);
+  }
+  return out;
+}
+function layersDroppedByRoles(requested, roles) {
+  const requestedSet = requested === void 0 || requested === "all" ? new Set(FEATURE_LAYERS) : new Set(requested);
+  const out = [];
+  for (const layer of FEATURE_LAYERS) {
+    if (!requestedSet.has(layer)) continue;
+    if (layerEnabledByRoles(layer, roles)) continue;
+    out.push(layer);
+  }
+  return out;
+}
+
+// src/feature/subcommand.ts
+var ACCEPTED_LAYER_VALUES = [...FEATURE_LAYERS, "all"];
+function parseFeatureAdd(args) {
+  let slug;
+  let layer;
+  let force = false;
+  let quiet = false;
+  let verbose = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    switch (a) {
+      case "--force":
+        force = true;
+        break;
+      case "--quiet":
+        quiet = true;
+        break;
+      case "--verbose":
+        verbose = true;
+        break;
+      case "--layer": {
+        const next = args[i + 1];
+        if (next === void 0 || next.startsWith("--")) {
+          throw new UserInputError(
+            "--layer requires a comma-separated list",
+            `\u793A\u4F8B\uFF1A--layer pm,backend,frontend\uFF1B\u53EF\u9009\u503C\uFF1A${ACCEPTED_LAYER_VALUES.join(",")}`
+          );
+        }
+        layer = parseLayerArg(next);
+        i += 1;
+        break;
+      }
+      default: {
+        if (a.startsWith("--")) {
+          throw new UserInputError(
+            `unknown option: ${a}`,
+            "\u67E5\u770B\u53EF\u7528\u9009\u9879\uFF1Acreate-keel feature add --help"
+          );
+        }
+        if (slug === void 0) {
+          slug = a;
+        } else {
+          throw new UserInputError(
+            `unexpected extra argument: ${JSON.stringify(a)}`,
+            "feature add \u6BCF\u6B21\u53EA\u80FD\u5904\u7406\u4E00\u4E2A slug"
+          );
+        }
+      }
+    }
+  }
+  if (slug === void 0) {
+    throw new UserInputError(
+      "missing <slug>",
+      "\u8BF7\u63D0\u4F9B feature slug\uFF0C\u4F8B\u5982\uFF1Acreate-keel feature add user-signup"
+    );
+  }
+  if (!isValidFeatureSlug(slug)) {
+    throw new UserInputError(
+      `invalid feature slug: ${JSON.stringify(slug)}`,
+      `slug \u5E94\u5339\u914D ${FEATURE_SLUG_PATTERN_SOURCE}\uFF0C\u4F8B\u5982\uFF1Auser-signup`
+    );
+  }
+  const flags = {
+    force,
+    quiet,
+    verbose,
+    ...layer !== void 0 ? { layer } : {}
+  };
+  return { slug, flags };
+}
+function parseLayerArg(raw) {
+  const parts = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (parts.length === 0) {
+    throw new UserInputError(
+      `invalid --layer value: ${JSON.stringify(raw)}`,
+      `\u53EF\u9009\u503C\uFF1A${ACCEPTED_LAYER_VALUES.join(",")}`
+    );
+  }
+  if (parts.includes("all")) {
+    if (parts.length > 1) {
+      throw new UserInputError(
+        `--layer all cannot be combined with other layer names`,
+        `\u4F20 'all' \u6216\u4E00\u4E2A\u660E\u786E\u5B50\u96C6\uFF0C\u4E0D\u8981\u6DF7\u7528`
+      );
+    }
+    return "all";
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const token of parts) {
+    if (!isFeatureLayer(token)) {
+      throw new UserInputError(
+        `invalid --layer value: ${JSON.stringify(token)}`,
+        `\u53EF\u9009\u503C\uFF1A${ACCEPTED_LAYER_VALUES.join(",")}`
+      );
+    }
+    if (seen.has(token)) {
+      throw new UserInputError(
+        `duplicate layer: ${token}`,
+        "--layer \u4E2D\u6BCF\u4E2A layer \u4EC5\u80FD\u51FA\u73B0\u4E00\u6B21"
+      );
+    }
+    seen.add(token);
+    out.push(token);
+  }
+  return out;
+}
+
 // src/cli.ts
 async function run(io) {
   const args = io.argv.slice(2);
@@ -167,12 +350,15 @@ async function run(io) {
     return 0;
   }
   const [command, ...rest] = args;
+  if (command === "feature") {
+    return await dispatchFeature(io, rest);
+  }
   if (command !== "create") {
     io.stderr(
       formatError(
         new UserInputError(
           `unknown command: ${JSON.stringify(command)}`,
-          "\u53EF\u7528\u7684\u547D\u4EE4\uFF1Acreate\u3002\u67E5\u770B\u5E2E\u52A9\uFF1A--help"
+          "\u53EF\u7528\u7684\u547D\u4EE4\uFF1Acreate / feature\u3002\u67E5\u770B\u5E2E\u52A9\uFF1A--help"
         )
       )
     );
@@ -200,6 +386,7 @@ function parseCreateArgs(args) {
   let config;
   let ci;
   let roles;
+  let sampleFeature = false;
   for (let i = 0; i < args.length; i += 1) {
     const a = args[i];
     switch (a) {
@@ -218,6 +405,9 @@ function parseCreateArgs(args) {
       case "--verbose":
         verbose = true;
         break;
+      case "--sample-feature":
+        sampleFeature = true;
+        break;
       case "--config": {
         const next = args[i + 1];
         if (next === void 0 || next.startsWith("--")) {
@@ -309,18 +499,66 @@ function parseCreateArgs(args) {
     verbose,
     ...config !== void 0 ? { config } : {},
     ...ci !== void 0 ? { ci } : {},
-    ...roles !== void 0 ? { roles } : {}
+    ...roles !== void 0 ? { roles } : {},
+    ...sampleFeature ? { sampleFeature: true } : {}
   };
+  if (sampleFeature && dryRun) {
+    throw new UserInputError(
+      `--sample-feature cannot be combined with --dry-run`,
+      "\u8BF7\u53BB\u6389\u4E00\u9879\u540E\u91CD\u8BD5"
+    );
+  }
   return { projectName, flags };
 }
+async function dispatchFeature(io, args) {
+  if (args.length === 0 || args.some((a) => a === "-h" || a === "--help")) {
+    io.stdout(featureHelpText());
+    return 0;
+  }
+  const [sub, ...rest] = args;
+  if (sub !== "add") {
+    io.stderr(
+      formatError(
+        new UserInputError(
+          `unknown feature subcommand: ${JSON.stringify(sub)}`,
+          "\u5F53\u524D\u53EF\u7528\uFF1Afeature add <slug>"
+        )
+      )
+    );
+    return 1;
+  }
+  if (io.onFeatureAdd === void 0) {
+    io.stderr(
+      formatError(
+        new UserInputError(
+          `feature add is not wired in this entry point`,
+          "\u8FD9\u662F\u4E00\u4E2A scaffolder \u5185\u90E8\u9519\u8BEF\uFF1AonFeatureAdd \u672A\u6CE8\u5165"
+        )
+      )
+    );
+    return 1;
+  }
+  try {
+    const parsed = parseFeatureAdd(rest);
+    await io.onFeatureAdd(parsed);
+    return 0;
+  } catch (err) {
+    io.stderr(formatError(err));
+    if (err instanceof ScaffolderError) {
+      return err.exitCode;
+    }
+    return 1;
+  }
+}
 function helpText() {
   return [
     "create-keel \u2014 scaffold a Contract-First project",
     "",
     "USAGE",
     "  npx @wneng/create-keel create <project-name> [options]",
+    "  npx @wneng/create-keel feature add <slug> [options]",
     "",
-    "OPTIONS",
+    "OPTIONS (create)",
     "  --yes              Skip interactive prompts and use defaults",
     "  --force            Overwrite a non-empty target directory after confirmation",
     "  --dry-run          Compute the plan without writing any files",
@@ -330,15 +568,42 @@ function helpText() {
     "  --ci <platform>    Which CI platform to scaffold (gitee|github, default: gitee)",
     "  --roles <list>     Comma-separated role directories to scaffold",
     "                     (" + ROLE_KINDS.join("|") + "; default: none)",
+    "  --sample-feature   After create, scaffold the user-signup sample feature",
     "  -h, --help         Show this help",
     "  -v, --version      Show the scaffolder version",
     "",
-    "See .kiro/specs/project-scaffolder/ for the full specification."
+    "OPTIONS (feature add)",
+    "  --layer <list>     Comma-separated layers to scaffold",
+    "                     (pm|arch|backend|frontend|test|all; default: all)",
+    "  --force            Overwrite existing Layer_Files for the requested layers",
+    "  --quiet            Only emit errors and the final summary",
+    "  --verbose          Emit per-file render/write logs",
+    "",
+    "See .kiro/specs/feature-subcommand/ for the full specification."
+  ].join("\n");
+}
+function featureHelpText() {
+  return [
+    "create-keel feature \u2014 manage features inside an existing keel project",
+    "",
+    "USAGE",
+    "  npx @wneng/create-keel feature add <slug> [options]",
+    "",
+    "OPTIONS",
+    "  --layer <list>     Comma-separated layers (pm|arch|backend|frontend|test|all)",
+    "  --force            Overwrite existing Layer_Files",
+    "  --quiet            Errors and summary only",
+    "  --verbose          Per-file render/write logs",
+    "",
+    "EXAMPLES",
+    "  feature add user-signup",
+    "  feature add billing-portal --layer pm,backend",
+    "  feature add legacy-import --force"
   ].join("\n");
 }
 
 // src/orchestrator.ts
-import * as path5 from "node:path";
+import * as path6 from "node:path";
 
 // src/input/defaults.ts
 var OPTION_DEFAULTS = {
@@ -399,8 +664,8 @@ var validate = ajv2.compile(
 function formatIssues() {
   const errs = validate.errors ?? [];
   return errs.map((e) => {
-    const path6 = e.instancePath || (e.params && "missingProperty" in e.params ? `/${String(e.params.missingProperty)}` : "<root>");
-    return `${path6}: ${e.message ?? "validation error"}`;
+    const path10 = e.instancePath || (e.params && "missingProperty" in e.params ? `/${String(e.params.missingProperty)}` : "<root>");
+    return `${path10}: ${e.message ?? "validation error"}`;
   }).join("; ");
 }
 async function loadConfigFile(filePath) {
@@ -897,9 +1162,21 @@ function buildRenderContext(input) {
     options: input.options,
     year: String(now.getUTCFullYear()),
     generatedAt: now.toISOString(),
-    scaffolderVersion: input.scaffolderVersion
+    scaffolderVersion: input.scaffolderVersion,
+    ...input.feature !== void 0 ? { feature: input.feature } : {}
   };
 }
+function buildFeatureContext(slug, nextAdrNumber) {
+  return {
+    slug,
+    title: slugToTitle(slug),
+    nextAdrNumber,
+    contractAnchor: `contracts/openapi/api.yaml#/paths/~1${slug}`
+  };
+}
+function slugToTitle(slug) {
+  return slug.split("-").filter((s) => s.length > 0).map((s) => s[0].toUpperCase() + s.slice(1)).join(" ");
+}
 
 // src/plan/builder.ts
 import { promises as fs4 } from "node:fs";
@@ -923,7 +1200,11 @@ function toStrictContext(ctx) {
     options: ctx.options,
     year: ctx.year,
     generatedAt: ctx.generatedAt,
-    scaffolderVersion: ctx.scaffolderVersion
+    scaffolderVersion: ctx.scaffolderVersion,
+    // `feature` is intentionally only attached when the orchestrator
+    // populated it; non-feature templates that try to read it will hit
+    // the proxy's "undefined template variable" branch.
+    ...ctx.feature !== void 0 ? { feature: ctx.feature } : {}
   };
   return new Proxy(base, {
     get(target, prop, receiver) {
@@ -1072,9 +1353,12 @@ function lowerExt(p) {
 // src/schema/metadata.ts
 import Ajv4 from "ajv";
 import addFormats2 from "ajv-formats";
+import { promises as fs5 } from "node:fs";
+import * as path4 from "node:path";
 var METADATA_FILENAME = ".scaffolder.json";
 var SEMVER_PATTERN2 = "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-.]+)?(?:\\+[0-9A-Za-z-.]+)?$";
 var FRAGMENT_NAME_PATTERN2 = "^[a-z0-9][a-z0-9-]{0,62}$";
+var FEATURE_SLUG_PATTERN2 = "^[a-z0-9][a-z0-9-]{0,62}$";
 var METADATA_SCHEMA = {
   $schema: "http://json-schema.org/draft-07/schema#",
   $id: "https://cgsy.example.com/schemas/scaffolder/metadata.json",
@@ -1097,17 +1381,48 @@ var METADATA_SCHEMA = {
           version: { type: "string", pattern: SEMVER_PATTERN2 }
         }
       }
+    },
+    features: {
+      type: "array",
+      items: { type: "string", pattern: FEATURE_SLUG_PATTERN2 },
+      uniqueItems: true
     }
   }
 };
 var ajv4 = new Ajv4({ allErrors: true, strict: true });
 addFormats2(ajv4);
 var validateFn3 = ajv4.compile(METADATA_SCHEMA);
+var MetadataValidationError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(
+      `Invalid ScaffolderMetadata:
+` + issues.map((i) => `  - ${i.path || "<root>"}: ${i.message}`).join("\n")
+    );
+    this.name = "MetadataValidationError";
+    this.issues = issues;
+  }
+};
+function collectIssues3() {
+  const errs = validateFn3.errors ?? [];
+  return errs.map((e) => ({
+    path: e.instancePath || (e.params && "missingProperty" in e.params ? `/${String(e.params.missingProperty)}` : ""),
+    message: e.message ?? "validation error"
+  }));
+}
+function assertMetadata(value) {
+  if (!validateFn3(value)) {
+    throw new MetadataValidationError(collectIssues3());
+  }
+  assertOptions(value.options);
+  return value;
+}
 var METADATA_TOP_ORDER = [
   "scaffolderVersion",
   "generatedAt",
   "options",
-  "templateFragments"
+  "templateFragments",
+  "features"
 ];
 function canonicalOptions(options) {
   const out = {};
@@ -1126,6 +1441,11 @@ function canonicalMetadata(metadata) {
       out[key] = canonicalOptions(metadata.options);
     } else if (key === "templateFragments") {
       out[key] = metadata.templateFragments.map(canonicalFragmentRef);
+    } else if (key === "features") {
+      const features = metadata.features;
+      if (features !== void 0 && features.length > 0) {
+        out[key] = [...features];
+      }
     } else {
       out[key] = metadata[key];
     }
@@ -1135,13 +1455,35 @@ function canonicalMetadata(metadata) {
 function serializeMetadata(metadata) {
   return JSON.stringify(canonicalMetadata(metadata), null, 2) + "\n";
 }
+function parseMetadata(input) {
+  let raw;
+  try {
+    raw = JSON.parse(input);
+  } catch (e) {
+    throw new MetadataValidationError([
+      { path: "", message: `invalid JSON: ${e.message}` }
+    ]);
+  }
+  return assertMetadata(raw);
+}
+async function writeMetadataFile(targetDirectory, metadata) {
+  const filePath = path4.join(targetDirectory, METADATA_FILENAME);
+  await fs5.writeFile(filePath, serializeMetadata(metadata), "utf8");
+  return filePath;
+}
+async function loadMetadataFile(targetDirectory) {
+  const filePath = path4.join(targetDirectory, METADATA_FILENAME);
+  const text = await fs5.readFile(filePath, "utf8");
+  return parseMetadata(text);
+}
 function buildMetadata(params) {
   const now = params.now ?? /* @__PURE__ */ new Date();
   return {
     scaffolderVersion: params.scaffolderVersion,
     generatedAt: now.toISOString(),
     options: params.options,
-    templateFragments: [...params.templateFragments]
+    templateFragments: [...params.templateFragments],
+    ...params.features !== void 0 ? { features: [...params.features] } : {}
   };
 }
 
@@ -1165,14 +1507,14 @@ function appendScaffolderMetadata(input) {
 }
 
 // src/writer/writer.ts
-import { promises as fs5 } from "node:fs";
-import * as path4 from "node:path";
+import { promises as fs6 } from "node:fs";
+import * as path5 from "node:path";
 var FORCE_BACKUP_BYTE_LIMIT = 10 * 1024 * 1024;
 async function writePlan(plan, opts) {
-  const absTarget = path4.resolve(opts.targetDirectory);
+  const absTarget = path5.resolve(opts.targetDirectory);
   const journal = { createdFiles: [], createdDirectories: [], overwrites: [] };
   const targetState = await inspectTarget(absTarget);
-  if (targetState.exists && targetState.nonEmpty && !opts.force) {
+  if (targetState.exists && targetState.nonEmpty && !opts.force && !opts.allowNonEmptyTarget) {
     throw new UserInputError(
       `target directory is not empty: ${absTarget}`,
       "\u4F7F\u7528\u4E0D\u540C\u8DEF\u5F84\uFF0C\u6216\u52A0 --force\uFF08\u5C0F\u5FC3\uFF1A\u4F1A\u8986\u76D6\u65E2\u6709\u6587\u4EF6\uFF09"
@@ -1183,13 +1525,13 @@ async function writePlan(plan, opts) {
   }
   try {
     if (!targetState.exists) {
-      await fs5.mkdir(absTarget, { recursive: true });
+      await fs6.mkdir(absTarget, { recursive: true });
       journal.createdDirectories.push(absTarget);
     }
     for (const rel of plan.directories) {
-      const abs = path4.join(absTarget, rel);
+      const abs = path5.join(absTarget, rel);
       try {
-        await fs5.mkdir(abs);
+        await fs6.mkdir(abs);
         journal.createdDirectories.push(abs);
       } catch (err) {
         if (err.code === "EEXIST") {
@@ -1199,18 +1541,18 @@ async function writePlan(plan, opts) {
       }
     }
     for (const file of plan.files) {
-      const abs = path4.join(absTarget, file.targetPath);
-      await fs5.mkdir(path4.dirname(abs), { recursive: true });
+      const abs = path5.join(absTarget, file.targetPath);
+      await fs6.mkdir(path5.dirname(abs), { recursive: true });
       if (opts.force) {
         try {
-          const prev = await fs5.readFile(abs, "utf8");
+          const prev = await fs6.readFile(abs, "utf8");
           journal.overwrites.push({ absPath: abs, originalContent: prev });
         } catch {
         }
       }
-      await fs5.writeFile(abs, file.content, "utf8");
+      await fs6.writeFile(abs, file.content, "utf8");
       if (file.mode !== void 0) {
-        await fs5.chmod(abs, file.mode);
+        await fs6.chmod(abs, file.mode);
       }
       journal.createdFiles.push(abs);
     }
@@ -1230,7 +1572,7 @@ async function writePlan(plan, opts) {
 }
 async function inspectTarget(absTarget) {
   try {
-    const entries = await fs5.readdir(absTarget);
+    const entries = await fs6.readdir(absTarget);
     return { exists: true, nonEmpty: entries.length > 0 };
   } catch (err) {
     const code = err.code;
@@ -1243,9 +1585,9 @@ async function inspectTarget(absTarget) {
 }
 async function preflightBackupCapacity(absTarget, plan) {
   for (const file of plan.files) {
-    const abs = path4.join(absTarget, file.targetPath);
+    const abs = path5.join(absTarget, file.targetPath);
     try {
-      const stat = await fs5.stat(abs);
+      const stat = await fs6.stat(abs);
       if (stat.isFile() && stat.size > FORCE_BACKUP_BYTE_LIMIT) {
         throw new UserInputError(
           `--force would overwrite ${abs} which is larger than the 10 MB rollback limit`,
@@ -1266,7 +1608,7 @@ async function rollback(journal) {
   for (let i = journal.overwrites.length - 1; i >= 0; i -= 1) {
     const { absPath, originalContent } = journal.overwrites[i];
     try {
-      await fs5.writeFile(absPath, originalContent, "utf8");
+      await fs6.writeFile(absPath, originalContent, "utf8");
     } catch {
     }
   }
@@ -1275,14 +1617,14 @@ async function rollback(journal) {
     const p = journal.createdFiles[i];
     if (overwriteSet.has(p)) continue;
     try {
-      await fs5.rm(p, { force: true });
+      await fs6.rm(p, { force: true });
     } catch {
     }
   }
   for (let i = journal.createdDirectories.length - 1; i >= 0; i -= 1) {
     const dir = journal.createdDirectories[i];
     try {
-      await fs5.rmdir(dir);
+      await fs6.rmdir(dir);
     } catch {
     }
   }
@@ -1390,7 +1732,7 @@ async function runCreate(input) {
   validatePlanSyntax(plan);
   reporter.info(`planned ${plan.files.length} file(s) across ${plan.directories.length} directory`);
   const cwd = input.io.cwd ?? process.cwd();
-  const targetDirectory = path5.resolve(cwd, options.projectName);
+  const targetDirectory = path6.resolve(cwd, options.projectName);
   if (input.flags.dryRun) {
     reporter.stage("dry-run");
     reporter.dryRunReport(plan);
@@ -1449,9 +1791,409 @@ async function resolveOptions(input) {
   return assertOptions(prompted);
 }
 
+// src/feature/orchestrator.ts
+import { promises as fs8 } from "node:fs";
+import * as path9 from "node:path";
+
+// src/feature/plan.ts
+import { promises as fs7, accessSync as accessSync2 } from "node:fs";
+import * as path7 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/feature/openapi-edit.ts
+import { isMap, isScalar, parseDocument, YAMLMap } from "yaml";
+function addPathStub(input) {
+  const insertedPath = input.path ?? `/${input.slug}`;
+  const doc = parseAndValidate(input.currentText);
+  const pathsNode = doc.get("paths", true);
+  let pathsMap;
+  if (pathsNode === void 0 || pathsNode === null || isScalar(pathsNode) && pathsNode.value === null) {
+    pathsMap = new YAMLMap();
+    pathsMap.flow = false;
+    doc.set("paths", pathsMap);
+  } else if (isMap(pathsNode)) {
+    pathsMap = pathsNode;
+    if (pathsMap.items.length === 0 && pathsMap.flow) {
+      pathsMap.flow = false;
+    }
+  } else {
+    throw new TemplateError(
+      `contracts/openapi/api.yaml: 'paths' is present but is not a map`,
+      "\u8BF7\u628A paths \u5B57\u6BB5\u5199\u6210 YAML \u6620\u5C04\uFF08\u4F8B\u5982 paths: {}\uFF09"
+    );
+  }
+  if (pathsMap.has(insertedPath)) {
+    return {
+      nextText: input.currentText,
+      insertedPath,
+      alreadyExisted: true
+    };
+  }
+  const operationKey = input.operation ?? "get";
+  const responses = input.responses ?? { "200": { description: "OK" } };
+  const operationBody = {
+    summary: input.title,
+    operationId: slugToOperationId(input.slug),
+    ...input.requestBody !== void 0 ? { requestBody: input.requestBody } : {},
+    responses
+  };
+  const stub = doc.createNode({
+    [operationKey]: operationBody
+  });
+  pathsMap.set(insertedPath, stub);
+  const nextText = serializeDocument(doc);
+  return {
+    nextText,
+    insertedPath,
+    alreadyExisted: false
+  };
+}
+function parseAndValidate(currentText) {
+  const doc = parseDocument(currentText, {
+    // keep node identity stable across parse → toString
+    keepSourceTokens: true
+  });
+  if (doc.errors.length > 0) {
+    const first = doc.errors[0];
+    throw yamlSyntaxError(first);
+  }
+  if (doc.contents === null) {
+    throw new TemplateError(
+      `contracts/openapi/api.yaml is empty; an OpenAPI 3.x document is required`,
+      "\u8BF7\u4FDD\u7559\u81F3\u5C11 openapi/info/paths \u4E09\u4E2A\u9876\u5C42\u5B57\u6BB5"
+    );
+  }
+  if (!isMap(doc.contents)) {
+    throw new TemplateError(
+      `contracts/openapi/api.yaml root must be a YAML mapping`,
+      "\u8BF7\u786E\u8BA4\u6587\u4EF6\u4EE5 openapi: ... \u5F00\u5934\uFF0C\u6839\u662F\u4E00\u4E2A\u6620\u5C04"
+    );
+  }
+  return doc;
+}
+function serializeDocument(doc) {
+  return doc.toString({
+    lineWidth: 0,
+    indent: 2
+  });
+}
+function yamlSyntaxError(err) {
+  const linePos = err.linePos;
+  const where = linePos !== void 0 ? `line ${linePos[0].line}, column ${linePos[0].col}` : `offset ${err.pos[0]}`;
+  return new UserInputError(
+    `contracts/openapi/api.yaml: YAML syntax error at ${where}: ${err.message}`,
+    "\u4FEE\u6B63 YAML \u8BED\u6CD5\u540E\u91CD\u8BD5\uFF0C\u5E38\u89C1\u539F\u56E0\uFF1A\u7F29\u8FDB / \u5F15\u53F7 / \u5192\u53F7\u540E\u7A7A\u683C\u7F3A\u5931"
+  );
+}
+function slugToOperationId(slug) {
+  return slug.replace(/-([a-z0-9])/g, (_m, c) => c.toUpperCase());
+}
+
+// src/feature/plan.ts
+async function buildFeaturePlan(input) {
+  const templatesRoot = input.templatesRoot ?? defaultFeatureTemplatesRoot();
+  const sourceRoot = input.source === "sample" ? path7.join(templatesRoot, "sample", input.slug) : templatesRoot;
+  const nextAdrNumber = await computeAdrNumberForSlug(input.cwd, input.slug);
+  const renderContext = buildRenderContext({
+    options: input.options,
+    scaffolderVersion: input.scaffolderVersion,
+    feature: buildFeatureContext(input.slug, nextAdrNumber),
+    ...input.now !== void 0 ? { now: input.now } : {}
+  });
+  const files = [];
+  const outputs = /* @__PURE__ */ new Map();
+  for (const layer of input.layers) {
+    const artifact = LAYER_ARTIFACTS[layer];
+    const targetPath = computeTargetPath(layer, input.slug, nextAdrNumber);
+    outputs.set(layer, targetPath);
+    const templatePath = path7.join(sourceRoot, artifact.placeholderTemplate);
+    const content = await renderFeatureTemplate(templatePath, renderContext, layer, input.source);
+    files.push({
+      targetPath,
+      content,
+      contributedBy: `feature:${layer}`
+    });
+  }
+  let openapiPathInserted;
+  let openapiAlreadyExisted;
+  if (input.layers.includes("backend") && input.options.contract !== "none") {
+    const apiPath = "contracts/openapi/api.yaml";
+    const apiAbs = path7.join(input.cwd, apiPath);
+    let currentText;
+    try {
+      currentText = await fs7.readFile(apiAbs, "utf8");
+    } catch (e) {
+      throw new TemplateError(
+        `expected ${apiPath} to exist when contract != 'none' but cannot read it: ${e.message}`,
+        "\u8BF7\u786E\u8BA4 contracts/openapi/api.yaml \u5B58\u5728\uFF1B\u6216\u5C06 .scaffolder.json \u4E2D options.contract \u8BBE\u4E3A none"
+      );
+    }
+    const editResult = input.source === "sample" && input.slug === "user-signup" ? addPathStub({
+      currentText,
+      slug: input.slug,
+      title: renderContext.feature.title,
+      // The sample feature owns its own canonical path + schema,
+      // satisfying Req 6.4 (request body schema + at least one
+      // response body schema).
+      path: "/users/signup",
+      operation: "post",
+      requestBody: {
+        required: true,
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              required: ["email", "password"],
+              properties: {
+                email: { type: "string", format: "email" },
+                password: { type: "string", minLength: 8 }
+              }
+            }
+          }
+        }
+      },
+      responses: {
+        "201": {
+          description: "User created in pending state; verification email sent",
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                required: ["id", "email", "state"],
+                properties: {
+                  id: { type: "string", format: "uuid" },
+                  email: { type: "string", format: "email" },
+                  state: { type: "string", enum: ["pending"] }
+                }
+              }
+            }
+          }
+        },
+        "409": {
+          description: "Email already registered (generic, does not leak existence)"
+        },
+        "429": { description: "Rate-limited" }
+      }
+    }) : addPathStub({
+      currentText,
+      slug: input.slug,
+      title: renderContext.feature.title
+    });
+    files.push({
+      targetPath: apiPath,
+      content: editResult.nextText,
+      contributedBy: "feature:openapi"
+    });
+    openapiPathInserted = editResult.insertedPath;
+    openapiAlreadyExisted = editResult.alreadyExisted;
+  }
+  const sortedFiles = [...files].sort(
+    (a, b) => a.targetPath < b.targetPath ? -1 : a.targetPath > b.targetPath ? 1 : 0
+  );
+  const directories = collectDirectories(sortedFiles);
+  return {
+    files: sortedFiles,
+    directories,
+    outputs,
+    ...openapiPathInserted !== void 0 ? { openapiPathInserted } : {},
+    ...openapiAlreadyExisted !== void 0 ? { openapiAlreadyExisted } : {}
+  };
+}
+function computeTargetPath(layer, slug, nextAdrNumber) {
+  if (layer === "arch") {
+    return `docs/02-\u7CFB\u7EDF\u65B9\u6848\u4E0E\u67B6\u6784/adr-${nextAdrNumber}-${slug}.md`;
+  }
+  return LAYER_ARTIFACTS[layer].outputPath(slug);
+}
+async function renderFeatureTemplate(templatePath, context, layer, source) {
+  try {
+    return await renderFile(templatePath, context);
+  } catch (e) {
+    throw new TemplateError(
+      `feature template missing for layer "${layer}" (${source}): ${templatePath}: ${e.message}`,
+      source === "sample" ? `\u8BF7\u786E\u8BA4 src/feature/templates/sample/<slug>/${LAYER_ARTIFACTS[layer].placeholderTemplate} \u5B58\u5728` : "\u8BF7\u786E\u8BA4 src/feature/templates/${layer}/ \u4E0B\u5B58\u5728 " + LAYER_ARTIFACTS[layer].placeholderTemplate
+    );
+  }
+}
+var ADR_FILE_RE = /^adr-(\d{4,})-/;
+async function computeAdrNumberForSlug(cwd, slug) {
+  const dir = path7.join(cwd, "docs", "02-\u7CFB\u7EDF\u65B9\u6848\u4E0E\u67B6\u6784");
+  let entries;
+  try {
+    entries = await fs7.readdir(dir);
+  } catch {
+    return "0001";
+  }
+  const slugRe = new RegExp(`^adr-(\\d{4,})-${escapeRegex(slug)}\\.md$`);
+  let max = 0;
+  for (const name of entries) {
+    const slugMatch = slugRe.exec(name);
+    if (slugMatch) {
+      return slugMatch[1];
+    }
+    const m = ADR_FILE_RE.exec(name);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (!Number.isNaN(n) && n > max) max = n;
+    }
+  }
+  return String(max + 1).padStart(4, "0");
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function collectDirectories(files) {
+  const set = /* @__PURE__ */ new Set();
+  for (const f of files) {
+    let cur = path7.posix.dirname(f.targetPath);
+    while (cur && cur !== "." && cur !== "/") {
+      set.add(cur);
+      cur = path7.posix.dirname(cur);
+    }
+  }
+  return [...set].sort();
+}
+function defaultFeatureTemplatesRoot() {
+  const here = path7.dirname(fileURLToPath2(import.meta.url));
+  const pkgRoot = findPackageRoot2(here);
+  return path7.join(pkgRoot, "src", "feature", "templates");
+}
+function findPackageRoot2(start) {
+  let dir = start;
+  for (let i = 0; i < 10; i += 1) {
+    const candidate = path7.join(dir, "package.json");
+    try {
+      accessSync2(candidate);
+      return dir;
+    } catch {
+    }
+    const parent = path7.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new TemplateError(
+    `unable to locate package.json above ${start}`,
+    "\u8BF7\u786E\u8BA4 scaffolder \u5B89\u88C5\u5B8C\u6574\uFF0Csrc/feature/templates/ \u4E0E package.json \u4F4D\u4E8E\u540C\u4E00\u5C42\u7EA7"
+  );
+}
+
+// src/feature/manifest-update.ts
+import * as path8 from "node:path";
+async function appendFeatureSlug(projectDirectory, slug) {
+  const manifest = await loadMetadataFile(projectDirectory);
+  const next = withFeatureSlug(manifest, slug);
+  const metadataPath = path8.join(projectDirectory, METADATA_FILENAME);
+  if (next === manifest) {
+    return { updated: false, metadataPath };
+  }
+  await writeMetadataFile(projectDirectory, next);
+  return { updated: true, metadataPath };
+}
+function withFeatureSlug(manifest, slug) {
+  const existing = manifest.features ?? [];
+  if (existing.includes(slug)) {
+    return manifest;
+  }
+  return {
+    ...manifest,
+    features: [...existing, slug]
+  };
+}
+
+// src/feature/orchestrator.ts
+async function runFeatureAdd(input) {
+  if (!isValidFeatureSlug(input.slug)) {
+    throw new UserInputError(
+      `invalid feature slug: ${JSON.stringify(input.slug)}`,
+      "slug \u5E94\u5339\u914D ^[a-z0-9][a-z0-9-]{0,62}$\uFF0C\u4F8B\u5982\uFF1Auser-signup"
+    );
+  }
+  let manifest;
+  try {
+    manifest = await loadMetadataFile(input.cwd);
+  } catch (e) {
+    const code = e.code;
+    if (code === "ENOENT") {
+      throw new UserInputError(
+        `no .scaffolder.json found at ${path9.join(input.cwd, METADATA_FILENAME)}`,
+        "\u8BF7\u5728 keel \u9879\u76EE\u6839\u76EE\u5F55\u8FD0\u884C\uFF1B\u6216\u5148\u7528 create-keel create \u521B\u5EFA\u9879\u76EE"
+      );
+    }
+    throw e;
+  }
+  const requested = input.layers ?? "all";
+  const resolved = resolveLayers(requested, manifest.options.roles);
+  const droppedByRoles = layersDroppedByRoles(requested, manifest.options.roles);
+  const featurePlan = await buildFeaturePlan({
+    slug: input.slug,
+    layers: resolved,
+    source: input.source,
+    options: manifest.options,
+    cwd: input.cwd,
+    scaffolderVersion: input.scaffolderVersion,
+    ...input.templatesRoot !== void 0 ? { templatesRoot: input.templatesRoot } : {},
+    ...input.now !== void 0 ? { now: input.now } : {}
+  });
+  const { toWrite, skipped } = await splitPlanByExistence(featurePlan, input.cwd, input.force);
+  if (toWrite.files.length > 0) {
+    await writePlan(toWrite, {
+      targetDirectory: input.cwd,
+      force: input.force,
+      allowNonEmptyTarget: true
+    });
+  }
+  const anchorsInserted = [];
+  if (featurePlan.openapiPathInserted !== void 0 && featurePlan.openapiAlreadyExisted === false && toWrite.files.some((f) => f.targetPath === "contracts/openapi/api.yaml")) {
+    anchorsInserted.push({
+      fromFile: "contracts/openapi/api.yaml",
+      toTarget: featurePlan.openapiPathInserted
+    });
+  }
+  const manifestResult = await appendFeatureSlug(input.cwd, input.slug);
+  return {
+    slug: input.slug,
+    created: toWrite.files.map((f) => f.targetPath),
+    skipped,
+    droppedByRoles,
+    anchorsInserted,
+    manifestUpdated: manifestResult.updated,
+    metadataPath: manifestResult.metadataPath
+  };
+}
+async function splitPlanByExistence(plan, cwd, force) {
+  if (force) {
+    return {
+      toWrite: { files: plan.files, directories: plan.directories },
+      skipped: []
+    };
+  }
+  const toWrite = [];
+  const skipped = [];
+  for (const file of plan.files) {
+    const exists = await fileExists(path9.join(cwd, file.targetPath));
+    if (exists) {
+      skipped.push(file.targetPath);
+    } else {
+      toWrite.push(file);
+    }
+  }
+  return {
+    toWrite: { files: toWrite, directories: plan.directories },
+    skipped
+  };
+}
+async function fileExists(absPath) {
+  try {
+    await fs8.access(absPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 async function handleCreate(input) {
-  await runCreate({
+  const result = await runCreate({
     projectName: input.projectName,
     flags: input.flags,
     io: {
@@ -1464,6 +2206,28 @@ async function handleCreate(input) {
       isTTY: Boolean(process.stdout.isTTY)
     }
   });
+  if (input.flags.sampleFeature === true && !result.dryRun) {
+    await runFeatureAdd({
+      slug: "user-signup",
+      cwd: result.targetDirectory,
+      source: "sample",
+      // Force is safe here: nothing pre-existing in a brand new project,
+      // so the writer's nonEmpty check is the only thing to bypass.
+      force: true,
+      scaffolderVersion: SCAFFOLDER_VERSION
+    });
+  }
+}
+async function handleFeatureAdd(input) {
+  const cwd = process.cwd();
+  await runFeatureAdd({
+    slug: input.slug,
+    cwd,
+    ...input.flags.layer !== void 0 ? { layers: input.flags.layer } : {},
+    source: "placeholder",
+    force: input.flags.force,
+    scaffolderVersion: SCAFFOLDER_VERSION
+  });
 }
 var exitCode = await run({
   argv: process.argv,
@@ -1473,7 +2237,8 @@ var exitCode = await run({
   stderr: (line) => {
     console.error(line);
   },
-  onCreate: handleCreate
+  onCreate: handleCreate,
+  onFeatureAdd: handleFeatureAdd
 });
 process.exit(exitCode);
 //# sourceMappingURL=index.js.map