create-kai 0.2.1 → 0.3.0

package/dist/index.js

@@ -159,9 +159,9 @@ var require_picocolors = __commonJS({
 
 // src/index.ts
 import { spawn } from "node:child_process";
-import { readdir as readdir2 } from "node:fs/promises";
-import { existsSync as existsSync2 } from "node:fs";
-import path2 from "node:path";
+import { readdir as readdir3 } from "node:fs/promises";
+import { existsSync as existsSync3 } from "node:fs";
+import path4 from "node:path";
 import process2 from "node:process";
 
 // node_modules/@clack/prompts/dist/index.mjs
@@ -864,6 +864,9 @@ var Y2 = ({ indicator: t = "dots" } = {}) => {
 // src/index.ts
 var import_picocolors3 = __toESM(require_picocolors(), 1);
 
+// src/args.ts
+import path from "node:path";
+
 // ../ui/src/agent-tooling/integrations/openai.ts
 var openai = {
   id: "openai",
@@ -3677,7 +3680,8 @@ var TAKES_VALUE = /* @__PURE__ */ new Set([
   "--widget-style",
   "--features",
   "--gateway",
-  "--kit"
+  "--kit",
+  "--shape"
 ]);
 function parseArgs(argv) {
   const out = { yes: false, list: false, json: false, help: false, version: false, errors: [] };
@@ -3706,6 +3710,9 @@ function parseArgs(argv) {
       case "--widget-style":
         out.widgetStyle = value;
         break;
+      case "--shape":
+        out.shape = value;
+        break;
       case "--features":
         out.features = value === void 0 || value === "" || value === "none" ? [] : value.split(",").map((f) => f.trim()).filter(Boolean);
         break;
@@ -3758,6 +3765,15 @@ function normalizeGateway(value) {
   if (value === void 0) return void 0;
   return value === "none" ? "mock" : value;
 }
+function sanitizeProjectName(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9-._~]/g, "-").replace(/^[._]+/, "");
+}
+function defaultNameForTarget(dirArg, cwd) {
+  if (dirArg === void 0) return ZERO_CONFIG.name;
+  const resolved = path.resolve(cwd, dirArg);
+  const sanitized = sanitizeProjectName(path.basename(resolved));
+  return sanitized.length > 0 && validateProjectName(sanitized) === null ? sanitized : ZERO_CONFIG.name;
+}
 function validateProjectName(name) {
   if (name.length === 0) return "Project name cannot be empty";
   if (name.length > 214) return "Project name must be 214 characters or fewer";
@@ -3841,7 +3857,7 @@ async function answerAxis(axis, opts, io) {
 // src/generate.ts
 import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import path from "node:path";
+import path2 from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/kai-json.ts
@@ -4329,7 +4345,7 @@ function travellingName(dotfile) {
 // src/generate.ts
 var GITIGNORE_TEMPLATE_NAME = travellingName(GITIGNORE_SOURCE_NAME);
 function defaultTemplateRoot() {
-  return path.join(path.dirname(fileURLToPath(import.meta.url)), "templates");
+  return path2.join(path2.dirname(fileURLToPath(import.meta.url)), "templates");
 }
 async function generate(plan, options = {}) {
   const framework = getFramework(plan.frameworkId);
@@ -4343,27 +4359,27 @@ async function generate(plan, options = {}) {
   }
   const emittedFeatures = surface.surface.features;
   const templateRoot = options.templateRoot ?? defaultTemplateRoot();
-  const templateDir = path.join(templateRoot, framework.templateDir);
+  const templateDir = path2.join(templateRoot, framework.templateDir);
   if (!existsSync(templateDir)) {
     throw new Error(
       `create-kai: no template for '${framework.id}' at ${templateDir}. Run the package build (it copies examples/starters/* into dist/templates).`
     );
   }
-  const parent = path.dirname(plan.dir);
+  const parent = path2.dirname(plan.dir);
   await mkdir(parent, { recursive: true });
-  const out = await mkdtemp(path.join(parent, ".create-kai-"));
+  const out = await mkdtemp(path2.join(parent, ".create-kai-"));
   let previousKitSpec;
   try {
     await cp(templateDir, out, { recursive: true });
     for (const dotfile of STRIPPED_DOTFILES) {
-      const travelling = path.join(out, travellingName(dotfile));
-      if (existsSync(travelling)) await rename(travelling, path.join(out, dotfile));
+      const travelling = path2.join(out, travellingName(dotfile));
+      if (existsSync(travelling)) await rename(travelling, path2.join(out, dotfile));
     }
     for (const patch of patchesFor(framework.templateDir)) {
-      const file = path.join(out, patch.file);
+      const file = path2.join(out, patch.file);
       await writeFile(file, applyPatch(patch, await readFile(file, "utf8"), plan.name), "utf8");
     }
-    const pkgPath = path.join(out, "package.json");
+    const pkgPath = path2.join(out, "package.json");
     const rewritten = rewritePackageJson(await readFile(pkgPath, "utf8"), {
       name: plan.name,
       kit: plan.kit,
@@ -4371,16 +4387,16 @@ async function generate(plan, options = {}) {
     });
     previousKitSpec = rewritten.previousKitSpec;
     await writeFile(pkgPath, stringifyPackageJson(rewritten.json), "utf8");
-    const appSource = await readFile(path.join(out, framework.paths.app), "utf8");
+    const appSource = await readFile(path2.join(out, framework.paths.app), "utf8");
     const thread = goLiveThread(appSource, framework);
     const routeFiles = await writeGateway(plan, framework, integration, out, thread);
     await writeFile(
-      path.join(out, "kai.json"),
+      path2.join(out, "kai.json"),
       stringifyKaiJson(buildKaiJson({ ...plan, featureIds: emittedFeatures }, framework)),
       "utf8"
     );
     await writeFile(
-      path.join(out, "README.md"),
+      path2.join(out, "README.md"),
       plan.gatewayId === "mock" ? renderMockReadme(plan, framework, thread, integration.docsSlug) : renderGatewayReadme(plan, framework, integration, routeFiles[0].path),
       "utf8"
     );
@@ -4419,12 +4435,12 @@ async function writeGateway(plan, framework, integration, out, thread) {
       );
     }
     for (const file of routeFiles) {
-      const abs = path.join(out, file.path);
-      await mkdir(path.dirname(abs), { recursive: true });
+      const abs = path2.join(out, file.path);
+      await mkdir(path2.dirname(abs), { recursive: true });
       await writeFile(abs, file.contents, "utf8");
     }
     for (const patch of gatewayPatchesFor(framework.templateDir)) {
-      const file = path.join(out, patch.file);
+      const file = path2.join(out, patch.file);
       await writeFile(
         file,
         applyGatewayPatch(patch, await readFile(file, "utf8"), {
@@ -4438,7 +4454,7 @@ async function writeGateway(plan, framework, integration, out, thread) {
     }
     if (integration.envVars.length > 0) {
       await writeFile(
-        path.join(out, framework.paths.env),
+        path2.join(out, framework.paths.env),
         renderEnvFile(integration.envVars, integration.runNote),
         "utf8"
       );
@@ -4553,7 +4569,7 @@ async function listFiles(dir, prefix = "") {
   const out = [];
   for (const entry of await readdir(dir)) {
     if (entry === "node_modules") continue;
-    const abs = path.join(dir, entry);
+    const abs = path2.join(dir, entry);
     const rel = prefix ? `${prefix}/${entry}` : entry;
     if ((await stat(abs)).isDirectory()) out.push(...await listFiles(abs, rel));
     else out.push(rel);
@@ -4574,11 +4590,166 @@ function detectPackageManager(userAgent = process.env.npm_config_user_agent) {
   return KNOWN.npm;
 }
 
+// src/wizard.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir as mkdir2, readdir as readdir2, writeFile as writeFile2 } from "node:fs/promises";
+import path3 from "node:path";
+var SCHEMA_URL = "https://ui.kitn.ai/schemas/construct/v1.json";
+function shapeAxis() {
+  const options = [
+    {
+      id: "widget",
+      label: "Embedded widget",
+      hint: "a floating launcher that sits on top of an existing page"
+    },
+    {
+      id: "fullscreen",
+      label: "Full-screen chat",
+      hint: "the chat is the whole page"
+    },
+    {
+      id: "app",
+      label: "Full app",
+      hint: "a scaffolded project with routing and a shell, not just a chat construct"
+    }
+  ];
+  return {
+    id: "shape",
+    label: "Shape",
+    question: "What are you building?",
+    options,
+    because: 'each shape needs a different tool: "widget" and "fullscreen" compose a construct (this wizard), while "app" needs the project scaffold this wizard does not build'
+  };
+}
+var DEFAULT_ATTACHMENTS_ACCEPT = ["image/*", "application/pdf"];
+var DEFAULT_HOME_GREETING_TITLE = "How can we help?";
+var CONSTRUCT_TAG_RE = /^[a-z][a-z0-9]*-[a-z0-9-]+$/;
+function constructTagName(projectName, shape) {
+  if (CONSTRUCT_TAG_RE.test(projectName)) return projectName;
+  let base = projectName.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  if (!/^[a-z]/.test(base)) {
+    base = base.length > 0 ? `k-${base}` : "k";
+  }
+  const suffix = shape === "widget" ? "widget" : "chat";
+  return `${base}-${suffix}`;
+}
+function composeConstruct(a) {
+  const capabilities = {};
+  if (a.starters.length > 0) capabilities.starters = a.starters;
+  if (a.attachments) capabilities.attachments = { accept: DEFAULT_ATTACHMENTS_ACCEPT };
+  if (a.history) {
+    capabilities.history = { persistence: "local" };
+    capabilities.conversations = true;
+  }
+  const construct = {
+    $schema: SCHEMA_URL,
+    // NOT `a.name` — see `constructTagName`'s header. The project directory
+    // name and the construct's own `Construct.name` are different
+    // vocabularies (directory rules vs. a custom-element tag rule), and this
+    // is the one place they're allowed to diverge.
+    name: constructTagName(a.name, a.shape),
+    layout: a.shape,
+    provider: { mode: "mock" }
+  };
+  if (a.headerTitle && a.headerTitle.length > 0) {
+    construct.header = { title: a.headerTitle };
+  }
+  if (a.home) {
+    const title = a.homeGreeting && a.homeGreeting.length > 0 ? a.homeGreeting : DEFAULT_HOME_GREETING_TITLE;
+    construct.home = { greeting: { title } };
+  }
+  if (a.accent && a.accent.length > 0) {
+    construct.theme = { accent: a.accent };
+  }
+  if (Object.keys(capabilities).length > 0) {
+    construct.capabilities = capabilities;
+  }
+  return construct;
+}
+async function emitConstruct(dir, answers) {
+  if (existsSync2(dir) && (await readdir2(dir)).length > 0) {
+    throw new Error(`${dir} already exists and is not empty`);
+  }
+  await mkdir2(dir, { recursive: true });
+  const construct = composeConstruct(answers);
+  const fileName = `${answers.name}.construct.json`;
+  const file = path3.join(dir, fileName);
+  await writeFile2(file, `${JSON.stringify(construct, null, 2)}
+`, "utf8");
+  return {
+    file,
+    devCommand: `npx @kitn.ai/ui dev ${fileName}`,
+    constructName: constructTagName(answers.name, answers.shape)
+  };
+}
+function runDevPreview(devCommand, cwd, spawnFn) {
+  return new Promise((resolve) => {
+    const [command, ...args] = devCommand.split(" ");
+    const child = spawnFn(command, args, {
+      cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32"
+    });
+    child.on("error", (err) => {
+      resolve({ ok: false, message: `could not start the preview: ${err.message}` });
+    });
+    child.on("close", (code, signal) => {
+      if (code === 0 || code === null) {
+        resolve({ ok: true, message: null });
+        return;
+      }
+      resolve({
+        ok: false,
+        message: `preview exited with code ${code}${signal ? ` (${signal})` : ""}`
+      });
+    });
+  });
+}
+async function runWizard(shape, name, io, nonInteractive) {
+  if (nonInteractive) {
+    return {
+      name,
+      shape,
+      headerTitle: "",
+      home: false,
+      homeGreeting: "",
+      starters: [],
+      attachments: false,
+      history: false,
+      accent: ""
+    };
+  }
+  io.state("Schema", `${SCHEMA_URL} \u2014 every construct the wizard emits stamps this so tooling can validate it`);
+  io.state("Name", `${name} \u2014 the project directory already fixed this`);
+  io.state("Provider", "mock \u2014 a keyless first run; switch providers in the construct file after");
+  const headerTitle = await io.text("Header title? (leave blank for none)", "");
+  const accent = await io.text("Accent color? (leave blank for the kit default)", "");
+  const home = await io.confirm("Show a home/greeting screen?", true);
+  const homeGreeting = home ? await io.text("Greeting title? (leave blank for the default)", DEFAULT_HOME_GREETING_TITLE) : "";
+  const starters = await io.multilineList("Starter prompts (comma-separated, up to 6, blank to skip)");
+  const attachments = await io.confirm("Allow file attachments?", false);
+  const history = await io.confirm("Persist conversation history in this browser?", true);
+  if (history) {
+    io.state("Conversations", "enabled \u2014 turned on automatically because history is on");
+  }
+  return {
+    name,
+    shape,
+    headerTitle,
+    home,
+    homeGreeting,
+    starters: starters.slice(0, 6),
+    attachments,
+    history,
+    accent
+  };
+}
+
 // src/index.ts
 var OFFERABLE_FEATURE_IDS = [
   ...new Set(readyFrameworks().flatMap((f) => availableFeatures(f).map((feature) => feature.id)))
 ];
-var DEFAULT_KIT_RANGE = "^0.27.0";
+var DEFAULT_KIT_RANGE = "^0.29.0";
 var HELP = `
 ${import_picocolors3.default.bold("create-kai")} \u2014 scaffold a runnable @kitn.ai/ui chat app
 
@@ -4609,7 +4780,7 @@ async function main() {
     return 0;
   }
   if (args.version) {
-    console.log("0.2.1");
+    console.log("0.3.0");
     return 0;
   }
   if (args.list) {
@@ -4618,7 +4789,7 @@ async function main() {
   }
   const nonInteractive = args.yes || !process2.stdout.isTTY;
   Ie(import_picocolors3.default.bgMagenta(import_picocolors3.default.black(" create-kai ")));
-  const defaultName = args.dir ?? ZERO_CONFIG.name;
+  const defaultName = defaultNameForTarget(args.dir, process2.cwd());
   const name = nonInteractive ? defaultName : await ask(
     he({
       message: "Project name",
@@ -4629,10 +4800,24 @@ async function main() {
   );
   const nameError = validateProjectName(name);
   if (nameError) return fail(nameError);
-  const dir = path2.resolve(process2.cwd(), args.dir ?? name);
-  if (existsSync2(dir) && (await readdir2(dir)).length > 0) {
+  const dir = path4.resolve(process2.cwd(), args.dir ?? name);
+  if (existsSync3(dir) && (await readdir3(dir)).length > 0) {
     return fail(`${dir} already exists and is not empty`);
   }
+  const shapes = shapeAxis();
+  if (args.shape !== void 0 && !shapes.options.some((o2) => o2.id === args.shape)) {
+    return fail(
+      `unknown shape '${args.shape}'. Available: ${shapes.options.map((o2) => o2.id).join(", ")}`
+    );
+  }
+  const shapeId = await answerAxis(
+    shapes,
+    { override: args.shape, nonInteractive, fallback: "app" },
+    clackAxisIo
+  );
+  if (shapeId !== "app") {
+    return runConstructFlow(shapeId, name, dir, nonInteractive);
+  }
   const frameworkId = args.framework ?? (nonInteractive ? ZERO_CONFIG.framework : await ask(
     ve({
       message: "Which framework?",
@@ -4729,7 +4914,7 @@ Available for ${framework.label}: ${featureList(offered)}`);
     // which kit the CLI was built against, which stays true when `--kit` sends
     // the dependency somewhere else — the emitted files are this version's shape
     // whatever the project ends up installing.
-    kitBuiltAgainst: "0.27.0"
+    kitBuiltAgainst: "0.29.0"
   };
   const spinner = Y2();
   spinner.start("Scaffolding");
@@ -4740,7 +4925,7 @@ Available for ${framework.label}: ${featureList(offered)}`);
     spinner.stop("Scaffolding failed");
     return fail(error instanceof Error ? error.message : String(error));
   }
-  spinner.stop(`Scaffolded ${import_picocolors3.default.cyan(path2.relative(process2.cwd(), dir) || ".")}`);
+  spinner.stop(`Scaffolded ${import_picocolors3.default.cyan(path4.relative(process2.cwd(), dir) || ".")}`);
   const pm = detectPackageManager();
   const shouldInstall = args.install ?? (nonInteractive ? false : await ask(ye({ message: `Install dependencies with ${pm.name}?`, initialValue: true })));
   let installed = false;
@@ -4755,7 +4940,7 @@ Available for ${framework.label}: ${featureList(offered)}`);
       install.stop(import_picocolors3.default.yellow(`${pm.name} install exited ${code} \u2014 run it yourself before ${pm.run}`));
     }
   }
-  const relative = path2.relative(process2.cwd(), dir);
+  const relative = path4.relative(process2.cwd(), dir);
   const integration = gateways.find((g2) => g2.integration.id === gatewayId)?.integration;
   const keyStep = gatewayId !== "mock" && integration && integration.envVars.length > 0 ? `# put your key in ${framework.paths.env} (${integration.envVars.join(", ")})` : null;
   const steps = [
@@ -4782,6 +4967,67 @@ async function ask(prompt) {
   }
   return value;
 }
+async function runConstructFlow(shape, name, dir, nonInteractive) {
+  const wizardIo = {
+    text: (msg, initial) => ask(he({ message: msg, defaultValue: initial ?? "", placeholder: initial })),
+    confirm: (msg, initial) => ask(ye({ message: msg, initialValue: initial })),
+    // A single comma-separated line rather than a repeated prompt, to keep the
+    // whole wizard to one screen — the brief's own call, not a schema
+    // requirement.
+    multilineList: async (msg) => {
+      const raw = await ask(
+        he({
+          message: msg,
+          placeholder: "e.g. Summarize this page, What can you help with?",
+          defaultValue: ""
+        })
+      );
+      return raw.split(",").map((s) => s.trim()).filter(Boolean).slice(0, 6);
+    },
+    state: stated
+  };
+  const answers = await runWizard(shape, name, wizardIo, nonInteractive);
+  const spinner = Y2();
+  spinner.start("Writing construct");
+  let result;
+  try {
+    result = await emitConstruct(dir, answers);
+  } catch (error) {
+    spinner.stop("Writing construct failed");
+    return fail(error instanceof Error ? error.message : String(error));
+  }
+  spinner.stop(`Wrote ${import_picocolors3.default.cyan(path4.relative(process2.cwd(), result.file))}`);
+  if (result.constructName !== name) {
+    stated(
+      "Construct name",
+      `${result.constructName} \u2014 "${name}" is not a valid custom-element tag; the directory and file name still use your name as typed`
+    );
+  }
+  const relative = path4.relative(process2.cwd(), dir);
+  const startPreview = !nonInteractive && await ask(ye({ message: "Start the live preview now?", initialValue: true }));
+  const printFallbackSteps = () => {
+    const steps = [relative ? `cd ${relative}` : null, result.devCommand].filter(Boolean);
+    Me(steps.join("\n"), "Next steps");
+  };
+  if (!startPreview) {
+    printFallbackSteps();
+  }
+  Se(
+    [
+      `${import_picocolors3.default.dim("Shape:")} ${shape}`,
+      `${import_picocolors3.default.dim("File:")}  ${path4.basename(result.file)}`
+    ].join("\n")
+  );
+  if (startPreview) {
+    const outcome = await runDevPreview(result.devCommand, dir, spawn);
+    if (!outcome.ok) {
+      console.error(import_picocolors3.default.red(`
+Live preview failed: ${outcome.message}`));
+      printFallbackSteps();
+    }
+  }
+  return 0;
+}
 function fail(message) {
   xe(import_picocolors3.default.red(message));
   return 1;
@@ -4811,12 +5057,12 @@ function run(command, cwd) {
 }
 function printMatrix(asJson) {
   const matrix = {
-    cli: "0.2.1",
+    cli: "0.3.0",
     kit: DEFAULT_KIT_RANGE,
     // The same pair `kai.json` carries. An agent reading this to decide what to
     // install gets the range; one reasoning about which kit the templates match
     // gets the exact version, without having to parse the range for a floor.
-    kitBuiltAgainst: "0.27.0",
+    kitBuiltAgainst: "0.29.0",
     frameworks: FRAMEWORKS.map((f) => ({
       id: f.id,
       label: f.label,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kai",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Scaffold a runnable @kitn.ai/ui chat app. `npm create kai@latest`",
   "license": "MIT",