@cementic/cementic-test 0.2.3 → 0.2.4

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import {
   genCmd
-} from "./chunk-J63TUHIV.js";
+} from "./chunk-3EE7LWWT.js";
 
 // src/cli.ts
 import { Command as Command9 } from "commander";
+import { createRequire } from "module";
 
 // src/commands/new.ts
 import { Command } from "commander";
@@ -16,12 +17,22 @@ import { dirname } from "path";
 import { platform, release } from "os";
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
+function resolveTemplatePath(templateDir) {
+  const candidates = [
+    resolve(__dirname, `templates/${templateDir}`),
+    resolve(__dirname, `../templates/${templateDir}`),
+    resolve(__dirname, `../../templates/${templateDir}`),
+    resolve(process.cwd(), `templates/${templateDir}`)
+  ];
+  return candidates.find((candidate) => existsSync(candidate));
+}
 function newCmd() {
   const cmd = new Command("new").arguments("<projectName>").description("Scaffold a new CementicTest + Playwright project from scratch").addHelpText("after", `
 Examples:
   $ ct new my-awesome-test-suite
+  $ ct new e2e-ts --lang ts
   $ ct new e2e-tests --no-browsers
-`).option("--mode <mode>", "greenfield|enhance", "greenfield").option("--no-browsers", 'do not run "npx playwright install" during setup').action((projectName, opts) => {
+`).option("--mode <mode>", "greenfield|enhance", "greenfield").option("--lang <lang>", "Scaffold language (js|ts)", "js").option("--no-browsers", 'do not run "npx playwright install" during setup').action((projectName, opts) => {
     const root = process.cwd();
     const projectPath = join(root, projectName);
     console.log(`\u{1F680} Initializing new CementicTest project in ${projectName}...`);
@@ -30,18 +41,11 @@ Examples:
       process.exit(1);
     }
     mkdirSync(projectPath, { recursive: true });
-    let templatePath = resolve(__dirname, "templates/student-framework");
-    if (!existsSync(templatePath)) {
-      templatePath = resolve(__dirname, "../templates/student-framework");
-    }
-    if (!existsSync(templatePath)) {
-      templatePath = resolve(__dirname, "../../templates/student-framework");
-    }
-    if (!existsSync(templatePath)) {
-      templatePath = resolve(process.cwd(), "templates/student-framework");
-    }
-    if (!existsSync(templatePath)) {
-      console.error(`\u274C Could not locate template at ${templatePath}`);
+    const lang = opts.lang === "ts" ? "ts" : "js";
+    const templateDir = lang === "ts" ? "student-framework-ts" : "student-framework";
+    const templatePath = resolveTemplatePath(templateDir);
+    if (!templatePath) {
+      console.error(`\u274C Could not locate template "${templateDir}"`);
       console.error("Please ensure the package is built correctly with templates included.");
       process.exit(1);
     }
@@ -129,6 +133,10 @@ function parseId(title) {
   const m = title.match(/\b([A-Z]+-\d+)\b/);
   return m?.[1];
 }
+function stripIdPrefixFromTitle(title, id) {
+  if (!id) return title.trim();
+  return title.replace(new RegExp(`^${id}\\s*[\u2014\\-\u2013:]\\s*`), "").trim();
+}
 function splitCasesByHeading(fileText) {
   const lines = fileText.split(/\r?\n/);
   const blocks = [];
@@ -190,18 +198,39 @@ function extractSections(body) {
   }
   return { steps, expected: expectedLines };
 }
+function extractUrlMetadata(body) {
+  const match = body.match(/<!--\s*ct:url\s+(https?:\/\/[^\s>]+)\s*-->/i);
+  return match?.[1];
+}
+function stripCtMetadata(body) {
+  return body.replace(/^\s*<!--\s*ct:url\s+https?:\/\/[^\s>]+\s*-->\s*\n?/im, "");
+}
+function extractUrlFromSteps(steps) {
+  for (const step of steps) {
+    const match = step.match(/https?:\/\/[^\s'"]+/i);
+    if (match) return match[0];
+  }
+  return void 0;
+}
 function normalizeOne(titleLine, body, source) {
   const { clean, tags } = parseTags(titleLine);
   const id = parseId(clean);
-  const { steps, expected } = extractSections(body);
+  const metadataUrl = extractUrlMetadata(body);
+  const cleanBody = stripCtMetadata(body);
+  const { steps, expected } = extractSections(cleanBody);
+  const reviewReasons = [];
+  if (steps.length === 0) reviewReasons.push("No steps section or bullets were parsed");
+  if (expected.length === 0) reviewReasons.push("No expected results section or assertions were parsed");
   return {
     id,
-    title: clean,
+    title: stripIdPrefixFromTitle(clean, id),
     tags: tags.length ? tags : void 0,
     steps,
     expected,
-    needs_review: steps.length === 0 || expected.length === 0,
-    source
+    needs_review: reviewReasons.length > 0,
+    review_reasons: reviewReasons,
+    source,
+    url: metadataUrl ?? extractUrlFromSteps(steps)
   };
 }
 function normalizeCmd() {
@@ -265,7 +294,7 @@ Examples:
     }
     console.log(`\u2705 Normalized ${index.summary.parsed} case(s). Output \u2192 .cementic/normalized/`);
     if (opts.andGen) {
-      const { gen } = await import("./gen-54KYT3RO.js");
+      const { gen } = await import("./gen-IO4KKGYY.js");
       await gen({ lang: opts.lang || "ts", out: "tests/generated" });
     }
   });
@@ -353,88 +382,136 @@ function inferPrefix(params) {
 // src/core/llm.ts
 function buildSystemMessage() {
   return `
-You are a senior QA engineer and test case designer.
+You are a senior QA engineer and test automation specialist.
 
 Your job:
-- Take the context of a web feature or page,
-- And generate high-quality UI test cases
-- In a very strict Markdown format that another tool will parse.
+- Receive context about a web feature or page
+- Generate high-quality, realistic UI test cases
+- Format them in strict Markdown that a downstream parser will process
 
 You MUST follow this format exactly for each test case:
 
-# <ID> \u2014 <Short title> @<tag1> @<tag2> ...
+# <ID> \u2014 <Short title> @<tag1> @<tag2>
 ## Steps
-1. <step>
-2. <step>
+1. <user action>
+2. <user action>
 
 ## Expected Results
-- <assertion>
-- <assertion>
+- <verifiable outcome>
+- <verifiable outcome>
 
 Rules:
-- <ID> must be PREFIX-XXX where PREFIX is provided to you (e.g., AUTH, DASH, CART).
-- XXX must be a 3-digit number starting from the startIndex provided in the context.
-  For example: DASH-005, DASH-006, DASH-007 if startIndex is 5.
-- Use 1\u20133 tags per test (e.g., @smoke, @regression, @auth, @ui, @critical).
-- "Steps" should describe user actions in sequence.
-- "Expected Results" should describe verifiable outcomes (URL change, element visible, message shown, etc.).
-- Do NOT add any explanation before or after the test cases.
-- Output ONLY the test cases, back-to-back, in Markdown.
-- No code blocks, no extra headings outside the pattern described.
+- ID must be PREFIX-NNN where NNN is zero-padded 3 digits starting from startIndex
+- Use 1\u20133 tags: @smoke @regression @auth @ui @critical @happy-path @negative
+- Steps = concrete user actions ("Click the 'Sign In' button", "Fill in email with 'user@example.com'")
+- Expected Results = verifiable UI outcomes ("Error message 'Invalid credentials' is visible", "Page redirects to /dashboard")
+- Include both happy-path AND negative/edge-case tests
+- Do NOT explain or add preamble \u2014 output ONLY the test cases
+- No code blocks, no extra headings outside the pattern
 `.trim();
 }
 function buildUserMessage(ctx) {
   const lines = [];
-  lines.push(`App / Product description (optional):`);
+  lines.push(`App / product description:`);
   lines.push(ctx.appDescription || "N/A");
   lines.push("");
   lines.push(`Feature or page to test:`);
   lines.push(ctx.feature);
   lines.push("");
   if (ctx.url) {
-    lines.push(`Page URL:`);
-    lines.push(ctx.url);
+    lines.push(`Page URL: ${ctx.url}`);
     lines.push("");
   }
-  if (ctx.pageSummaryJson) {
-    lines.push(`Page structure summary (JSON):`);
-    lines.push("```json");
-    lines.push(JSON.stringify(ctx.pageSummaryJson, null, 2));
-    lines.push("```");
+  if (ctx.pageSummary) {
+    const s = ctx.pageSummary;
+    lines.push(`Live page analysis:`);
+    if (s.title) lines.push(`- Page title: ${s.title}`);
+    if (s.headings.length) {
+      lines.push(`- Headings: ${s.headings.join(" | ")}`);
+    }
+    if (s.inputs.length) {
+      const inputDescs = s.inputs.map((i) => {
+        const parts = [
+          i.label && `label="${i.label}"`,
+          i.placeholder && `placeholder="${i.placeholder}"`,
+          i.name && `name="${i.name}"`,
+          i.type && i.type !== "text" && `type="${i.type}"`,
+          i.testId && `data-testid="${i.testId}"`
+        ].filter(Boolean);
+        return parts.join(", ");
+      });
+      lines.push(`- Form inputs: ${inputDescs.join(" | ")}`);
+    }
+    if (s.buttons.length) {
+      lines.push(`- Buttons: ${s.buttons.join(" | ")}`);
+    }
+    if (s.links.length) {
+      lines.push(`- Links: ${s.links.slice(0, 20).join(" | ")}`);
+    }
     lines.push("");
   }
-  lines.push(`Test ID prefix to use: ${ctx.prefix}`);
-  lines.push(
-    `Start numbering from: ${String(ctx.startIndex).padStart(3, "0")}`
-  );
-  lines.push(`Number of test cases to generate: ${ctx.numCases}`);
-  lines.push("");
-  lines.push(`Important formatting rules:`);
-  lines.push(`- Use IDs like ${ctx.prefix}-NNN where NNN is 3-digit, sequential from the start index.`);
-  lines.push(`- Each test case must follow this pattern exactly:`);
-  lines.push(`# ${ctx.prefix}-NNN \u2014 <short title> @tag1 @tag2`);
-  lines.push(`## Steps`);
-  lines.push(`1. ...`);
-  lines.push(`2. ...`);
-  lines.push(``);
-  lines.push(`## Expected Results`);
-  lines.push(`- ...`);
-  lines.push(`- ...`);
+  lines.push(`Test ID prefix: ${ctx.prefix}`);
+  lines.push(`Start numbering from: ${String(ctx.startIndex).padStart(3, "0")}`);
+  lines.push(`Number of test cases: ${ctx.numCases}`);
   lines.push("");
-  lines.push(`Do NOT add any explanation before or after the test cases. Only output the test cases.`);
+  lines.push(`Include a mix of: happy-path flows, validation/error cases, and edge cases.`);
+  lines.push(`Output ONLY the test cases. No explanation, no preamble.`);
   return lines.join("\n");
 }
-async function generateTcMarkdownWithAi(ctx) {
-  const apiKey = process.env.CT_LLM_API_KEY || process.env.OPENAI_API_KEY || "";
-  if (!apiKey) {
-    throw new Error(
-      "No LLM API key found. Set CT_LLM_API_KEY or OPENAI_API_KEY."
-    );
+function detectProvider() {
+  const anthropicKey = process.env.ANTHROPIC_API_KEY ?? process.env.CT_ANTHROPIC_API_KEY ?? "";
+  const openaiKey = process.env.CT_LLM_API_KEY ?? process.env.OPENAI_API_KEY ?? "";
+  const explicitProvider = (process.env.CT_LLM_PROVIDER ?? "").toLowerCase();
+  if (explicitProvider === "anthropic" || anthropicKey && explicitProvider !== "openai") {
+    if (!anthropicKey) {
+      throw new Error(
+        "CT_LLM_PROVIDER=anthropic but no ANTHROPIC_API_KEY found.\nSet ANTHROPIC_API_KEY=your-key or switch to OPENAI_API_KEY."
+      );
+    }
+    return {
+      provider: "anthropic",
+      apiKey: anthropicKey,
+      model: process.env.CT_LLM_MODEL ?? "claude-sonnet-4-5",
+      baseUrl: "https://api.anthropic.com"
+    };
   }
-  const baseUrl = process.env.CT_LLM_BASE_URL || "https://api.openai.com/v1";
-  const model = process.env.CT_LLM_MODEL || "gpt-4.1-mini";
-  const system = buildSystemMessage();
-  const user = buildUserMessage(ctx);
+  if (openaiKey) {
+    return {
+      provider: "openai",
+      apiKey: openaiKey,
+      model: process.env.CT_LLM_MODEL ?? "gpt-4o-mini",
+      baseUrl: process.env.CT_LLM_BASE_URL ?? "https://api.openai.com/v1"
+    };
+  }
+  throw new Error(
+    "No LLM API key found.\n  For Claude:  export ANTHROPIC_API_KEY=your-key\n  For OpenAI:  export OPENAI_API_KEY=your-key\n  Any OpenAI-compatible endpoint: set CT_LLM_API_KEY + CT_LLM_BASE_URL"
+  );
+}
+async function callAnthropic(apiKey, model, system, user) {
+  const response = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 4096,
+      system,
+      messages: [{ role: "user", content: user }]
+    })
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Anthropic API error ${response.status}: ${text}`);
+  }
+  const json = await response.json();
+  const content = json.content?.[0]?.text?.trim() ?? "";
+  if (!content) throw new Error("Anthropic response had no content");
+  return content;
+}
+async function callOpenAi(apiKey, model, baseUrl, system, user) {
   const response = await fetch(`${baseUrl}/chat/completions`, {
     method: "POST",
     headers: {
@@ -443,68 +520,145 @@ async function generateTcMarkdownWithAi(ctx) {
     },
     body: JSON.stringify({
       model,
+      temperature: 0.2,
       messages: [
         { role: "system", content: system },
         { role: "user", content: user }
-      ],
-      temperature: 0.2
+      ]
     })
   });
   if (!response.ok) {
     const text = await response.text();
-    throw new Error(
-      `LLM request failed: ${response.status} ${response.statusText} \u2014 ${text}`
-    );
+    throw new Error(`OpenAI API error ${response.status}: ${text}`);
   }
   const json = await response.json();
-  const content = json.choices?.[0]?.message?.content?.trim() || "";
-  if (!content) {
-    throw new Error("LLM response had no content");
-  }
+  const content = json.choices?.[0]?.message?.content?.trim() ?? "";
+  if (!content) throw new Error("OpenAI response had no content");
   return content;
 }
+async function generateTcMarkdownWithAi(ctx) {
+  const { provider, apiKey, model, baseUrl } = detectProvider();
+  const system = buildSystemMessage();
+  const user = buildUserMessage(ctx);
+  console.log(`\u{1F916} Using ${provider === "anthropic" ? "Claude" : "OpenAI-compatible"} (${model})`);
+  if (provider === "anthropic") {
+    return callAnthropic(apiKey, model, system, user);
+  }
+  return callOpenAi(apiKey, model, baseUrl, system, user);
+}
 
 // src/core/scrape.ts
 async function scrapePageSummary(url) {
-  const res = await fetch(url);
+  try {
+    return await scrapeWithPlaywright(url);
+  } catch (pwErr) {
+    console.warn(`\u26A0\uFE0F  Playwright scrape failed (${pwErr?.message ?? pwErr}). Falling back to static fetch.`);
+    return scrapeWithFetch(url);
+  }
+}
+async function scrapeWithPlaywright(url) {
+  let chromium;
+  try {
+    ({ chromium } = await import("playwright-core"));
+  } catch {
+    ({ chromium } = await import("@playwright/test"));
+  }
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    userAgent: "Mozilla/5.0 (compatible; CementicTest-scraper/1.0)"
+  });
+  const page = await context.newPage();
+  try {
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 2e4 });
+    await page.waitForTimeout(800);
+    const summary = await page.evaluate(() => {
+      const text = (el) => el?.textContent?.replace(/\s+/g, " ").trim() ?? "";
+      const attr = (el, a) => el?.getAttribute(a)?.trim() ?? "";
+      const title = document.title?.trim() || void 0;
+      const headings = Array.from(document.querySelectorAll("h1, h2")).map((h) => text(h)).filter(Boolean).slice(0, 20);
+      const buttons = Array.from(
+        document.querySelectorAll('button, [role="button"]')
+      ).map((b) => attr(b, "aria-label") || text(b)).filter(Boolean).slice(0, 30);
+      const links = Array.from(document.querySelectorAll("a[href]")).map((a) => attr(a, "aria-label") || text(a)).filter(Boolean).slice(0, 50);
+      const inputs = [];
+      document.querySelectorAll("input, textarea, select").forEach((el) => {
+        const id = attr(el, "id");
+        const name = attr(el, "name") || void 0;
+        const ph = attr(el, "placeholder") || void 0;
+        const type = attr(el, "type") || void 0;
+        const testId = attr(el, "data-testid") || void 0;
+        let labelText;
+        if (id) {
+          const labelEl = document.querySelector(`label[for="${id}"]`);
+          if (labelEl) labelText = text(labelEl) || void 0;
+        }
+        if (!labelText) {
+          const closest = el.closest("label");
+          if (closest) labelText = text(closest).replace(ph ?? "", "").trim() || void 0;
+        }
+        if (labelText || ph || name || testId) {
+          inputs.push({ label: labelText, placeholder: ph, name, type, testId });
+        }
+      });
+      const landmarks = Array.from(
+        document.querySelectorAll('[role="navigation"], [role="main"], [role="form"], nav, main, form')
+      ).map((el) => attr(el, "aria-label") || el.tagName.toLowerCase()).filter(Boolean);
+      const rawLength = document.documentElement.outerHTML.length;
+      return {
+        title,
+        headings,
+        buttons,
+        links,
+        inputs: inputs.slice(0, 30),
+        landmarks,
+        rawLength
+      };
+    });
+    return { url, ...summary };
+  } finally {
+    await browser.close();
+  }
+}
+async function scrapeWithFetch(url) {
+  const res = await fetch(url, {
+    headers: { "User-Agent": "CementicTest-scraper/1.0" }
+  });
   if (!res.ok) {
-    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+    throw new Error(`HTTP ${res.status} ${res.statusText} \u2014 ${url}`);
   }
   const html = await res.text();
   const rawLength = html.length;
   const titleMatch = html.match(/<title[^>]*>([^<]*)<\/title>/i);
   const title = titleMatch?.[1]?.trim() || void 0;
-  const headings = Array.from(html.matchAll(/<(h1|h2)[^>]*>([^<]*)<\/\1>/gi)).map((m) => m[2].replace(/\s+/g, " ").trim()).filter(Boolean);
-  const buttons = Array.from(html.matchAll(/<button[^>]*>([^<]*)<\/button>/gi)).map((m) => m[1].replace(/\s+/g, " ").trim()).filter(Boolean);
+  const headings = Array.from(html.matchAll(/<(h1|h2)[^>]*>([^<]*)<\/\1>/gi)).map((m) => m[2].replace(/\s+/g, " ").trim()).filter(Boolean).slice(0, 20);
+  const buttons = Array.from(html.matchAll(/<button[^>]*>([^<]*)<\/button>/gi)).map((m) => m[1].replace(/\s+/g, " ").trim()).filter(Boolean).slice(0, 30);
   const links = Array.from(html.matchAll(/<a[^>]*>([^<]*)<\/a>/gi)).map((m) => m[1].replace(/\s+/g, " ").trim()).filter(Boolean).slice(0, 50);
-  const inputs = [];
   const labelMap = /* @__PURE__ */ new Map();
   for (const m of html.matchAll(/<label[^>]*for=["']?([^"'>\s]+)["']?[^>]*>([^<]*)<\/label>/gi)) {
-    const id = m[1];
-    const text = m[2].replace(/\s+/g, " ").trim();
+    const id = m[1], text = m[2].replace(/\s+/g, " ").trim();
     if (id && text) labelMap.set(id, text);
   }
+  const inputs = [];
   for (const m of html.matchAll(/<input([^>]*)>/gi)) {
     const attrs = m[1];
-    const nameMatch = attrs.match(/\bname=["']?([^"'>\s]+)["']?/i);
-    const idMatch = attrs.match(/\bid=["']?([^"'>\s]+)["']?/i);
-    const phMatch = attrs.match(/\bplaceholder=["']([^"']*)["']/i);
-    const id = idMatch?.[1];
+    const name = attrs.match(/\bname=["']?([^"'>\s]+)["']?/i)?.[1];
+    const id = attrs.match(/\bid=["']?([^"'>\s]+)["']?/i)?.[1];
+    const ph = attrs.match(/\bplaceholder=["']([^"']*)["']/i)?.[1]?.trim();
+    const type = attrs.match(/\btype=["']?([^"'>\s]+)["']?/i)?.[1];
+    const testId = attrs.match(/\bdata-testid=["']([^"']*)["']/i)?.[1]?.trim();
     const label = id ? labelMap.get(id) : void 0;
-    const ph = phMatch?.[1]?.trim();
-    const name = nameMatch?.[1];
-    const descriptor = label || ph || name;
-    if (descriptor) {
-      inputs.push(descriptor);
+    if (label || ph || name || testId) {
+      inputs.push({ label, placeholder: ph, name, type, testId });
     }
   }
   return {
     url,
     title,
-    headings: headings.slice(0, 20),
-    buttons: buttons.slice(0, 30),
+    headings,
+    buttons,
     links,
     inputs: inputs.slice(0, 30),
+    landmarks: [],
     rawLength
   };
 }
@@ -513,6 +667,18 @@ async function scrapePageSummary(url) {
 function slugify(text) {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "tc";
 }
+function injectUrlMetadata(markdown, url) {
+  if (!url || /<!--\s*ct:url\s+/i.test(markdown)) return markdown;
+  const lines = markdown.split("\n");
+  const output2 = [];
+  for (let i = 0; i < lines.length; i++) {
+    output2.push(lines[i]);
+    if (/^\s*#\s+/.test(lines[i])) {
+      output2.push(`<!-- ct:url ${url} -->`);
+    }
+  }
+  return output2.join("\n");
+}
 function buildManualCasesMarkdown(opts) {
   const { prefix, feature, url, numCases } = opts;
   const startIndex = opts.startIndex ?? 1;
@@ -520,9 +686,8 @@ function buildManualCasesMarkdown(opts) {
   for (let i = 0; i < numCases; i++) {
     const idx = startIndex + i;
     const id = `${prefix}-${String(idx).padStart(3, "0")}`;
-    const title = `${feature} - scenario ${idx}`;
-    const tags = "@regression @ui";
-    lines.push(`# ${id} \u2014 ${title} ${tags}`);
+    lines.push(`# ${id} \u2014 ${feature} - scenario ${idx} @regression @ui`);
+    if (url) lines.push(`<!-- ct:url ${url} -->`);
     lines.push(`## Steps`);
     lines.push(`1. Navigate to ${url ?? "<PAGE_URL>"}`);
     lines.push(`2. Perform the main user action for this scenario`);
@@ -538,12 +703,10 @@ function buildManualCasesMarkdown(opts) {
 }
 async function promptBasicQuestions(opts) {
   if (opts.feature) {
-    let n = opts.numCases ?? 3;
-    if (n < 1) n = 3;
-    if (n > 10) n = 10;
+    const n = Math.min(Math.max(opts.numCases ?? 3, 1), 10);
     return {
       feature: opts.feature,
-      appDescription: opts.appDescription || "",
+      appDescription: opts.appDescription ?? "",
       numCases: n,
       url: opts.url
     };
@@ -551,16 +714,13 @@ async function promptBasicQuestions(opts) {
   const rl = createInterface({ input, output });
   const feature = (await rl.question("\u{1F9E9} Feature or page to test: ")).trim();
   const appDescription = (await rl.question("\u{1F4DD} Short app description (optional): ")).trim();
-  const numCasesRaw = (await rl.question("\u{1F522} How many test cases? (1-10) [3]: ")).trim();
+  const numCasesRaw = (await rl.question("\u{1F522} How many test cases? (1\u201310) [3]: ")).trim();
   rl.close();
   let numCases = parseInt(numCasesRaw, 10);
   if (isNaN(numCases) || numCases < 1) numCases = 3;
   if (numCases > 10) numCases = 10;
   return { feature, appDescription, numCases, url: opts.url };
 }
-function hasAiFlagInArgv() {
-  return process.argv.includes("--ai");
-}
 async function runTcInteractive(params) {
   const { feature, appDescription, numCases, url } = await promptBasicQuestions({
     url: params.url,
@@ -576,84 +736,95 @@ async function runTcInteractive(params) {
   mkdirSync3("cases", { recursive: true });
   const fileName = `${prefix.toLowerCase()}-${slugify(feature)}.md`;
   const fullPath = join3("cases", fileName);
-  const useAi = hasAiFlagInArgv();
-  console.log(`\u2699\uFE0F Debug: useAi=${useAi}, argv=${JSON.stringify(process.argv)}`);
   let markdown;
-  if (useAi) {
-    let pageSummaryJson = void 0;
+  if (params.useAi) {
+    let pageSummary = void 0;
     if (url) {
       try {
-        console.log(`\u{1F50D} Scraping page for AI context: ${url}`);
-        pageSummaryJson = await scrapePageSummary(url);
+        console.log(`\u{1F50D} Scraping page: ${url}`);
+        pageSummary = await scrapePageSummary(url);
         console.log(
-          `\u{1F50E} Scrape summary: title="${pageSummaryJson.title || ""}", headings=${pageSummaryJson.headings.length}, buttons=${pageSummaryJson.buttons.length}, inputs=${pageSummaryJson.inputs.length}`
+          `   Found: ${pageSummary.headings.length} heading(s), ${pageSummary.inputs.length} input(s), ${pageSummary.buttons.length} button(s)`
         );
       } catch (e) {
-        console.warn(
-          `\u26A0\uFE0F Failed to scrape ${url} (${e?.message || e}). Continuing without page summary.`
-        );
+        console.warn(`\u26A0\uFE0F  Scrape failed (${e?.message ?? e}). Continuing without page context.`);
       }
     }
     try {
-      console.log("\u{1F916} AI: generating test cases...");
       markdown = await generateTcMarkdownWithAi({
         appDescription: appDescription || void 0,
         feature,
         url,
-        pageSummaryJson,
+        pageSummary,
         prefix,
         startIndex: 1,
         numCases
       });
-      console.log("\u2705 AI: generated test case markdown.");
+      markdown = injectUrlMetadata(markdown, url);
+      console.log("\u2705 AI generated test cases.");
     } catch (err) {
-      console.warn(
-        `\u26A0\uFE0F AI generation failed (${err?.message || err}). Falling back to manual templates.`
-      );
-      markdown = buildManualCasesMarkdown({
-        prefix,
-        feature,
-        url,
-        numCases,
-        startIndex: 1
-      });
-      console.log("\u{1F4DD} Manual: generated test case templates instead.");
+      console.warn(`\u26A0\uFE0F  AI generation failed (${err?.message ?? err}). Falling back to manual templates.`);
+      markdown = buildManualCasesMarkdown({ prefix, feature, url, numCases, startIndex: 1 });
+      console.log("\u{1F4DD} Generated manual test case templates instead.");
     }
   } else {
-    markdown = buildManualCasesMarkdown({
-      prefix,
-      feature,
-      url,
-      numCases,
-      startIndex: 1
-    });
-    console.log("\u{1F4DD} Manual: generated test case templates (no --ai).");
+    markdown = buildManualCasesMarkdown({ prefix, feature, url, numCases, startIndex: 1 });
+    console.log("\u{1F4DD} Generated manual test case templates (pass --ai to use AI).");
   }
   writeFileSync3(fullPath, markdown);
-  console.log(`\u270D\uFE0F Wrote ${numCases} test case(s) \u2192 ${fullPath}`);
-  console.log("Next steps:");
+  console.log(`
+\u270D\uFE0F  Wrote ${numCases} case(s) \u2192 ${fullPath}`);
+  console.log("\nNext steps:");
   console.log("  ct normalize ./cases --and-gen --lang ts");
   console.log("  ct test");
 }
+function addSharedOptions(cmd) {
+  return cmd.option("--ai", "Use AI to generate test cases (requires API key)").option("--prefix <prefix>", "Explicit ID prefix, e.g. AUTH, DASH, CART").option("--feature <name>", "Feature name \u2014 skips interactive prompt").option("--desc <text>", "App description \u2014 skips interactive prompt").option("--count <n>", "Number of cases (1\u201310)", parseInt);
+}
+function resolveCommanderOpts(opts) {
+  if (typeof opts.optsWithGlobals === "function") {
+    return opts.optsWithGlobals();
+  }
+  if (typeof opts.opts === "function") {
+    return opts.opts();
+  }
+  return opts;
+}
 function tcCmd() {
-  const root = new Command4("tc").description("Create CT-style test cases (Markdown) under ./cases").option("--ai", "Use AI if configured (BYO LLM API key).", false).option("--prefix <prefix>", "Explicit ID prefix, e.g. AUTH, DASH, CART").option("--feature <name>", "Feature name (non-interactive)").option("--desc <text>", "App description (non-interactive)").option("--count <n>", "Number of cases (non-interactive)", parseInt).action(async (opts) => {
-    await runTcInteractive({
-      url: void 0,
-      explicitPrefix: opts.prefix,
-      feature: opts.feature,
-      appDescription: opts.desc,
-      numCases: opts.count
-    });
-  });
-  root.command("url").argument("<url>", "Page URL to use as context").option("--ai", "Use AI if configured (BYO LLM API key).", false).option("--prefix <prefix>", "Explicit ID prefix, e.g. AUTH, DASH, CART").option("--feature <name>", "Feature name (non-interactive)").option("--desc <text>", "App description (non-interactive)").option("--count <n>", "Number of cases (non-interactive)", parseInt).description("Create test cases with awareness of a specific page URL").action(async (url, opts) => {
-    await runTcInteractive({
-      url,
-      explicitPrefix: opts.prefix,
-      feature: opts.feature,
-      appDescription: opts.desc,
-      numCases: opts.count
-    });
-  });
+  const root = new Command4("tc").description("Create CementicTest case files (Markdown) under ./cases").addHelpText("after", `
+Examples:
+  $ ct tc --feature "Login form" --ai
+  $ ct tc --feature "Checkout" --count 5 --prefix CHK
+  $ ct tc url https://example.com/login --ai --feature "Auth"
+`);
+  addSharedOptions(root).action(
+    async (opts) => {
+      const resolvedOpts = resolveCommanderOpts(opts);
+      await runTcInteractive({
+        url: void 0,
+        explicitPrefix: resolvedOpts.prefix,
+        feature: resolvedOpts.feature,
+        appDescription: resolvedOpts.desc,
+        numCases: resolvedOpts.count,
+        useAi: resolvedOpts.ai ?? false
+      });
+    }
+  );
+  addSharedOptions(
+    root.command("url").argument("<url>", "Page URL to use as scraping and AI context").description("Generate test cases with awareness of a specific live page")
+  ).action(
+    async (url, opts, command) => {
+      const resolvedOpts = resolveCommanderOpts(command ?? opts);
+      await runTcInteractive({
+        url,
+        explicitPrefix: resolvedOpts.prefix,
+        feature: resolvedOpts.feature,
+        appDescription: resolvedOpts.desc,
+        numCases: resolvedOpts.count,
+        useAi: resolvedOpts.ai ?? false
+      });
+    }
+  );
   return root;
 }
 
@@ -808,8 +979,10 @@ function ciCmd() {
 }
 
 // src/cli.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
 var program = new Command9();
-program.name("cementic-test").description("CementicTest CLI: cases \u2192 normalized \u2192 POM tests \u2192 Playwright").version("0.2.0");
+program.name("ct").description("CementicTest CLI: cases \u2192 normalized \u2192 POM tests \u2192 Playwright").version(version);
 program.addCommand(newCmd());
 program.addCommand(normalizeCmd());
 program.addCommand(genCmd());