create-oke 0.1.4 → 0.2.1

package/src/cli.ts

@@ -1,17 +1,34 @@
 /**
- * `create-oke` CLI — one command, sensible default, done.
+ * `create-oke` CLI — clean templates by default; teaching examples opt-in.
  *
  * ```bash
- * bunx create-oke@latest <name> [--template notes|linkly|provisions|skyport]
+ * bunx create-oke@latest <name> [--template hello|minimal|standard|full]
+ * bunx create-oke@latest <name> --from-example notes|linkly|provisions|skyport
+ * bunx create-oke@latest   # interactive when stdin is a TTY
  * ```
  */
 
+import {
+  cancel,
+  intro,
+  isCancel,
+  outro,
+  select,
+  spinner,
+  text,
+} from "@clack/prompts";
 import { basename, relative, resolve } from "node:path";
-import { scaffold } from "./scaffold.ts";
+import { existsSync, rmSync } from "node:fs";
+import { scaffold, type ScaffoldResult, type ScaffoldSource } from "./scaffold.ts";
 import {
   DEFAULT_TEMPLATE,
+  EXAMPLE_NEW_IDEAS,
+  EXAMPLES,
+  TEMPLATE_PURPOSES,
   TEMPLATES,
+  isExampleId,
   isTemplateId,
+  type ExampleId,
   type TemplateId,
 } from "./templates.ts";
 
@@ -19,10 +36,40 @@ import {
 export type CliArgs = {
   readonly name: string | undefined;
   readonly template: TemplateId;
+  readonly fromExample: ExampleId | undefined;
+  /** True when `--template` / `-t` was present on the argv. */
+  readonly templateExplicit: boolean;
   readonly help: boolean;
   readonly targetDir: string | undefined;
 };
 
+/**
+ * Sentinel choice for "Start from a worked example" in interactive answers.
+ * Distinct from clack's internal select value (`__example__`).
+ */
+export const FROM_EXAMPLE_CHOICE = "from-example" as const;
+
+/** Answers collected by the interactive ask step (no clack types). */
+export type InteractiveAnswers =
+  | {
+      readonly name: string;
+      readonly choice: TemplateId;
+    }
+  | {
+      readonly name: string;
+      readonly choice: typeof FROM_EXAMPLE_CHOICE;
+      readonly example: ExampleId;
+    };
+
+/**
+ * Canonical scaffold invocation — shared by interactive and flag-driven paths.
+ */
+export type ScaffoldCallArgs = {
+  readonly name: string;
+  readonly targetDir: string;
+  readonly source: ScaffoldSource;
+};
+
 /**
  * Parse argv after the binary name.
  *
@@ -31,6 +78,8 @@ export type CliArgs = {
 export function parseArgs(argv: readonly string[]): CliArgs {
   let name: string | undefined;
   let template: TemplateId = DEFAULT_TEMPLATE;
+  let fromExample: ExampleId | undefined;
+  let templateExplicit = false;
   let help = false;
   let targetDir: string | undefined;
 
@@ -48,6 +97,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
         );
       }
       template = next;
+      templateExplicit = true;
       continue;
     }
     if (a.startsWith("--template=")) {
@@ -58,6 +108,27 @@ export function parseArgs(argv: readonly string[]): CliArgs {
         );
       }
       template = value;
+      templateExplicit = true;
+      continue;
+    }
+    if (a === "--from-example") {
+      const next = argv[++i];
+      if (!next || !isExampleId(next)) {
+        throw new Error(
+          `create-oke: --from-example must be one of ${EXAMPLES.join("|")}`,
+        );
+      }
+      fromExample = next;
+      continue;
+    }
+    if (a.startsWith("--from-example=")) {
+      const value = a.slice("--from-example=".length);
+      if (!isExampleId(value)) {
+        throw new Error(
+          `create-oke: --from-example must be one of ${EXAMPLES.join("|")}`,
+        );
+      }
+      fromExample = value;
       continue;
     }
     if (a.startsWith("-")) {
@@ -70,11 +141,17 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     throw new Error(`create-oke: unexpected argument ${a}`);
   }
 
+  if (templateExplicit && fromExample !== undefined) {
+    throw new Error(
+      "create-oke: use either --template or --from-example, not both",
+    );
+  }
+
   if (name !== undefined) {
     targetDir = resolve(name);
   }
 
-  return { name, template, help, targetDir };
+  return { name, template, fromExample, templateExplicit, help, targetDir };
 }
 
 /**
@@ -88,32 +165,218 @@ export function formatCdPath(targetDir: string): string {
   return rel;
 }
 
+/**
+ * Post-scaffold next-steps block — shared by interactive and flag-driven paths.
+ *
+ * @param result - Successful scaffold result
+ */
+export function nextStepsText(result: ScaffoldResult): string {
+  return `
+Scaffolded ${result.label} → ${result.targetDir}
+
+Next steps:
+
+  cd ${formatCdPath(result.targetDir)}
+  bun install
+  oke dev          # app :6530 · Console :6533 · MCP :6535
+`;
+}
+
 /**
  * Help text — next steps match four-applications.md (`bun install` · `oke dev`).
  */
 export function helpText(): string {
+  const templateLines = TEMPLATES.map(
+    (id) =>
+      `  ${id.padEnd(12)}${TEMPLATE_PURPOSES[id]}${id === DEFAULT_TEMPLATE ? "  (default)" : ""}`,
+  ).join("\n");
+  const exampleLines = EXAMPLES.map(
+    (id) => `  ${id.padEnd(12)}${EXAMPLE_NEW_IDEAS[id]}`,
+  ).join("\n");
+
   return `create-oke — scaffold an okengine app
 
 Usage:
-  bunx create-oke@latest <name> [--template notes|linkly|provisions|skyport]
+  bunx create-oke@latest <name> [--template hello|minimal|standard|full]
+  bunx create-oke@latest <name> --from-example notes|linkly|provisions|skyport
+  bunx create-oke@latest          # interactive (TTY only)
+
+Templates (clean starters from templates/):
+${templateLines}
 
-Templates (from examples/):
-  notes        basic — Flow · Store                         (default)
-  linkly       intermediate — + Signal · Clock · Gate
-  provisions   advanced — + Vault · Channel · plugins
-  skyport      complex — all eight elements · AI · tenancy
+--from-example (copies a teaching example, including its business logic and
+comments — most new projects want --template instead):
+${exampleLines}
 
-No telemetry. Bun only. No interactive wizard.
+No telemetry. Bun only. Interactive prompts only when stdin is a TTY and no
+name / --template / --from-example is given.
 `;
 }
 
+/**
+ * Whether the CLI should open the two-question interactive flow.
+ *
+ * Mirrors oke / gflows: bare invocation is interactive only in a real terminal;
+ * any explicit flag or positional name stays fully scriptable.
+ *
+ * @param args - Parsed args
+ * @param stdinIsTTY - `process.stdin.isTTY`
+ */
+export function shouldPrompt(
+  args: CliArgs,
+  stdinIsTTY: boolean | undefined,
+): boolean {
+  if (!stdinIsTTY) return false;
+  if (args.help) return false;
+  if (args.name !== undefined) return false;
+  if (args.templateExplicit) return false;
+  if (args.fromExample !== undefined) return false;
+  return true;
+}
+
+/**
+ * Build the {@link ScaffoldSource} for a flag-driven invocation.
+ *
+ * @param args - Parsed args
+ */
+export function sourceFromArgs(args: CliArgs): ScaffoldSource {
+  if (args.fromExample !== undefined) {
+    return { kind: "example", id: args.fromExample };
+  }
+  return { kind: "template", id: args.template };
+}
+
+/**
+ * Map flag-driven {@link CliArgs} to scaffold call args.
+ *
+ * Requires a positional project name (and thus `targetDir`).
+ *
+ * @param args - Parsed CLI args with `name` set
+ */
+export function scaffoldArgsFromCli(args: CliArgs): ScaffoldCallArgs {
+  if (args.name === undefined || args.targetDir === undefined) {
+    throw new Error("create-oke: missing <name>");
+  }
+  return {
+    name: basename(resolve(args.name)),
+    targetDir: args.targetDir,
+    source: sourceFromArgs(args),
+  };
+}
+
+/**
+ * Pure map from interactive answers → scaffold call args.
+ *
+ * Independent of clack — unit-tested against {@link scaffoldArgsFromCli}
+ * for every template and every `--from-example` choice.
+ *
+ * @param answers - Collected interactive answers
+ */
+export function scaffoldArgsFromAnswers(
+  answers: InteractiveAnswers,
+): ScaffoldCallArgs {
+  const targetDir = resolve(answers.name.trim());
+  const name = basename(targetDir);
+  if (answers.choice === FROM_EXAMPLE_CHOICE) {
+    return {
+      name,
+      targetDir,
+      source: { kind: "example", id: answers.example },
+    };
+  }
+  return {
+    name,
+    targetDir,
+    source: { kind: "template", id: answers.choice },
+  };
+}
+
+/**
+ * Ask step — clack prompts only. Returns answers or `null` on cancel.
+ *
+ * Injectable for tests; production uses {@link askInteractiveAnswers}.
+ *
+ * @param partial - Name already known (skipped in the prompt)
+ */
+export type AskInteractiveFn = (
+  partial: { readonly name?: string },
+) => Promise<InteractiveAnswers | null>;
+
+/**
+ * Collect interactive answers via `@clack/prompts`.
+ *
+ * @param partial - Optional pre-filled project name
+ * @returns Answers, or `null` if the user cancelled
+ */
+export async function askInteractiveAnswers(
+  partial: { readonly name?: string } = {},
+): Promise<InteractiveAnswers | null> {
+  let name = partial.name;
+  if (name === undefined) {
+    const nameValue = await text({
+      message: "Project name",
+      placeholder: "my-app",
+      validate: (value) => {
+        if (!value?.trim()) return "Project name is required";
+        return undefined;
+      },
+    });
+    if (isCancel(nameValue)) return null;
+    name = String(nameValue).trim();
+  }
+
+  const templateValue = await select({
+    message: "Template",
+    options: [
+      ...TEMPLATES.map((id) => ({
+        value: id as string,
+        label: id,
+        hint: TEMPLATE_PURPOSES[id],
+      })),
+      {
+        value: "__example__",
+        label: "Start from a worked example",
+        hint: "Teaching apps with business logic — most projects want a template",
+      },
+    ],
+    initialValue: DEFAULT_TEMPLATE,
+  });
+  if (isCancel(templateValue)) return null;
+
+  if (templateValue === "__example__") {
+    const exampleValue = await select({
+      message: "Example",
+      options: EXAMPLES.map((id) => ({
+        value: id,
+        label: id,
+        hint: EXAMPLE_NEW_IDEAS[id],
+      })),
+    });
+    if (isCancel(exampleValue)) return null;
+    return {
+      name,
+      choice: FROM_EXAMPLE_CHOICE,
+      example: exampleValue as ExampleId,
+    };
+  }
+
+  return { name, choice: templateValue as TemplateId };
+}
+
 /**
  * Run the CLI.
  *
  * @param argv - Args after the binary
+ * @param options - Test seams (stdin TTY, ask injection)
  * @returns Exit code
  */
-export async function run(argv: readonly string[]): Promise<number> {
+export async function run(
+  argv: readonly string[],
+  options: {
+    readonly stdinIsTTY?: boolean | undefined;
+    readonly ask?: AskInteractiveFn;
+  } = {},
+): Promise<number> {
   let args: CliArgs;
   try {
     args = parseArgs(argv);
@@ -122,35 +385,98 @@ export async function run(argv: readonly string[]): Promise<number> {
     return 1;
   }
 
-  if (args.help || args.name === undefined) {
+  if (args.help) {
     console.log(helpText());
-    if (args.name === undefined && !args.help) {
-      console.error("create-oke: missing <name>");
-      return 1;
-    }
-    return args.help ? 0 : 1;
+    return 0;
   }
 
-  const projectName = basename(resolve(args.name));
-  try {
-    const result = scaffold({
-      targetDir: args.targetDir!,
-      name: projectName,
-      template: args.template,
-    });
+  const stdinIsTTY = options.stdinIsTTY ?? process.stdin.isTTY;
+  if (shouldPrompt(args, stdinIsTTY)) {
+    return runInteractive(args, options.ask ?? askInteractiveAnswers);
+  }
 
-    console.log(`
-Scaffolded ${result.template} → ${result.targetDir}
+  if (args.name === undefined) {
+    console.log(helpText());
+    console.error("create-oke: missing <name>");
+    return 1;
+  }
 
-Next steps:
+  return runScaffold({
+    ...scaffoldArgsFromCli(args),
+    interactive: false,
+  });
+}
 
-  cd ${formatCdPath(result.targetDir)}
-  bun install
-  oke dev          # app :6530 · Console :6533 · MCP :6535
-`);
+/**
+ * Interactive TTY flow — ask → map answers → scaffold.
+ *
+ * @param args - Parsed args (name may already be set if ever called that way)
+ * @param ask - Injectable ask step
+ */
+async function runInteractive(
+  args: CliArgs,
+  ask: AskInteractiveFn,
+): Promise<number> {
+  intro("create-oke");
+
+  const answers = await ask({ name: args.name });
+  if (answers === null) {
+    cancel("Cancelled.");
+    return 1;
+  }
+
+  return runScaffold({
+    ...scaffoldArgsFromAnswers(answers),
+    interactive: true,
+  });
+}
+
+/**
+ * Scaffold with optional spinner / outro, cleaning up on failure or cancel.
+ *
+ * @param options - Scaffold inputs + interactive flag
+ */
+async function runScaffold(
+  options: ScaffoldCallArgs & { readonly interactive: boolean },
+): Promise<number> {
+  const { name, targetDir, source, interactive } = options;
+  const existed = existsSync(targetDir);
+  let spun: ReturnType<typeof spinner> | undefined;
+
+  const cleanup = (): void => {
+    if (!existed && existsSync(targetDir)) {
+      rmSync(targetDir, { recursive: true, force: true });
+    }
+  };
+
+  const onSigInt = (): void => {
+    spun?.stop("Cancelled.");
+    cleanup();
+    if (interactive) cancel("Cancelled.");
+    process.exit(1);
+  };
+  process.once("SIGINT", onSigInt);
+
+  try {
+    if (interactive) {
+      spun = spinner();
+      spun.start("Scaffolding…");
+    }
+    const result = scaffold({ targetDir, name, source });
+    if (spun) spun.stop("Scaffolded.");
+    const message = nextStepsText(result);
+    if (interactive) {
+      outro(message.trim());
+    } else {
+      console.log(message);
+    }
     return 0;
   } catch (e) {
+    spun?.stop("Failed.");
+    cleanup();
     console.error(e instanceof Error ? e.message : e);
     return 1;
+  } finally {
+    process.off("SIGINT", onSigInt);
   }
 }

package/src/index.ts

@@ -1,6 +1,14 @@
 #!/usr/bin/env bun
 /**
- * `create-oke` binary entry.
+ * `create-oke` binary entry — scaffold an okengine app.
+ *
+ * ```bash
+ * bunx create-oke@latest my-app
+ * bunx create-oke@latest my-app --template hello
+ * bunx create-oke@latest my-app --from-example notes
+ * ```
+ *
+ * @module
  */
 
 import { run } from "./cli.ts";

package/src/scaffold.ts

@@ -1,5 +1,5 @@
 /**
- * Copy an `examples/<template>` tree and apply the package.json transform.
+ * Copy a template or example tree and apply the package.json transform.
  */
 
 import {
@@ -8,13 +8,16 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import {
+  resolveExampleDir,
   resolveLocalOkengineRoot,
   resolveTemplateDir,
+  type ExampleId,
   type TemplateId,
 } from "./templates.ts";
 import {
@@ -25,35 +28,46 @@ import {
   type ScaffoldPackageJson,
 } from "./transform.ts";
 
+/** Where the scaffold copies from. */
+export type ScaffoldSource =
+  | { readonly kind: "template"; readonly id: TemplateId }
+  | { readonly kind: "example"; readonly id: ExampleId };
+
 /** Options for {@link scaffold}. */
 export type ScaffoldOptions = {
   /** Destination directory (created). Absolute or cwd-relative. */
   readonly targetDir: string;
   /** npm package / folder name. */
   readonly name: string;
-  /** Template id (default: notes). */
-  readonly template: TemplateId;
+  /** Template or teaching-example source. */
+  readonly source: ScaffoldSource;
 };
 
 /** Result of a successful scaffold. */
 export type ScaffoldResult = {
   readonly targetDir: string;
   readonly name: string;
-  readonly template: TemplateId;
+  readonly source: ScaffoldSource;
+  /** Display label (`standard`, `notes`, …). */
+  readonly label: string;
   readonly okengineDependency: string;
   /** Relative paths written (POSIX), sorted. */
   readonly files: readonly string[];
 };
 
 /**
- * Scaffold a new okengine project from `examples/<template>`.
+ * Scaffold a new okengine project from a clean template or teaching example.
  *
- * @param options - Name, template, destination
+ * @param options - Name, source, destination
  */
 export function scaffold(options: ScaffoldOptions): ScaffoldResult {
   const name = sanitizeProjectName(options.name);
   const targetDir = resolve(options.targetDir);
-  const templateDir = resolveTemplateDir(options.template);
+  const sourceDir =
+    options.source.kind === "template"
+      ? resolveTemplateDir(options.source.id)
+      : resolveExampleDir(options.source.id);
+  const label = options.source.id;
 
   if (existsSync(targetDir)) {
     const entries = readdirSync(targetDir);
@@ -66,33 +80,37 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
     mkdirSync(targetDir, { recursive: true });
   }
 
-  const okengineDependency = resolveOkengineDependency(
-    resolveLocalOkengineRoot(),
-  );
-  const written: string[] = [];
+  try {
+    const okengineDependency = resolveOkengineDependency(
+      resolveLocalOkengineRoot(),
+    );
+    const written: string[] = [];
 
-  copyTree(templateDir, targetDir, "", written);
+    copyTree(sourceDir, targetDir, "", written);
 
-  const pkgPath = join(targetDir, "package.json");
-  if (!existsSync(pkgPath)) {
-    throw new Error(
-      `create-oke: template "${options.template}" has no package.json`,
-    );
-  }
-  const sourcePkg = JSON.parse(
-    readFileSync(pkgPath, "utf8"),
-  ) as ScaffoldPackageJson;
-  const nextPkg = transformPackageJson(sourcePkg, name, okengineDependency);
-  writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`, "utf8");
+    const pkgPath = join(targetDir, "package.json");
+    if (!existsSync(pkgPath)) {
+      throw new Error(`create-oke: source "${label}" has no package.json`);
+    }
+    const sourcePkg = JSON.parse(
+      readFileSync(pkgPath, "utf8"),
+    ) as ScaffoldPackageJson;
+    const nextPkg = transformPackageJson(sourcePkg, name, okengineDependency);
+    writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`, "utf8");
 
-  written.sort();
-  return {
-    targetDir,
-    name,
-    template: options.template,
-    okengineDependency,
-    files: written,
-  };
+    written.sort();
+    return {
+      targetDir,
+      name,
+      source: options.source,
+      label,
+      okengineDependency,
+      files: written,
+    };
+  } catch (e) {
+    rmSync(targetDir, { recursive: true, force: true });
+    throw e;
+  }
 }
 
 /**
@@ -129,7 +147,7 @@ function copyTree(
 }
 
 /**
- * List relative file paths in an example tree using the same skip rules as scaffold.
+ * List relative file paths in a source tree using the same skip rules as scaffold.
  *
  * @param templateDir - Absolute template directory
  */