create-ovok 0.1.0-dev.13 → 0.1.0-dev.21

package/README.md

@@ -1,11 +1,28 @@
 # create-ovok
 
 ```bash
-pnpm create ovok my-app --platform web|mobile|mobile-web [--type ios|android] [--tenant <code>] [--base-url <url>]
+pnpm create ovok my-app
 ```
 
-Missing options are asked for on a terminal. The result is a Turborepo with the chosen apps in
-`apps/`, the Ovok API and tenant in `.env`, and the Ovok MCP server in `.mcp.json`.
+It asks for the project name, then offers the recommended setup (web and mobile apps, iOS and
+Android, the Ovok sandbox) or lets you choose each part. It then runs `pnpm install` and makes
+the first git commit. The result is a Turborepo with the chosen apps in `apps/`, the Ovok API
+and tenant in `.env`, and the Ovok MCP server in `.mcp.json`.
+
+Flags answer their questions, and `--yes` takes the recommended setup for the rest:
+
+| Flag | Answers |
+|---|---|
+| `--platform web\|mobile\|mobile-web` | The apps to start with |
+| `--type ios\|android` | One mobile platform instead of both |
+| `--tenant <code>` | The Ovok tenant code |
+| `--base-url <url>` | The Ovok API URL |
+| `-y`, `--yes` | Every question no flag answered, with the recommended setup |
+| `--skip-install` | Leaves `pnpm install` to you |
+| `--disable-git` | Leaves the folder without a git repository |
+
+Outside a terminal, such as in CI, nothing is asked: unanswered questions take the recommended
+setup.
 
 Inside the workspace:
 

package/dist/adapters/clack-prompt.js

@@ -0,0 +1,28 @@
+import { isCancel, select, text } from "@clack/prompts";
+import { CancelledError, } from "../application/workspace-answers.js";
+/** Arrow-key and typed answers in a terminal; an empty answer takes the fallback. */
+export class ClackPrompt {
+    async text(question) {
+        const answer = await text({
+            message: question.message,
+            placeholder: question.fallback,
+            defaultValue: question.fallback,
+            validate: (value) => question.validate(value || question.fallback) ?? undefined,
+        });
+        return answered(answer);
+    }
+    async select(question) {
+        const answer = await select({
+            message: question.message,
+            // Clack's Option is conditional on T, which a generic T cannot resolve.
+            options: question.options.map((choice) => ({ ...choice })),
+            initialValue: question.fallback,
+        });
+        return answered(answer);
+    }
+}
+function answered(answer) {
+    if (isCancel(answer))
+        throw new CancelledError("Cancelled.");
+    return answer;
+}

package/dist/adapters/git-repository.js

@@ -0,0 +1,24 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const INITIAL_COMMIT_MESSAGE = "chore: initial commit from create-ovok";
+/** A new repository with the scaffold as its first commit, unless the folder is in one already. */
+export async function initialiseGitRepository(directory) {
+    if (await succeeds(["rev-parse", "--is-inside-work-tree"], directory))
+        return "inside-repository";
+    if (!(await succeeds(["init", "--quiet", "--initial-branch=main"], directory))) {
+        return "unavailable";
+    }
+    const committed = (await succeeds(["add", "--all"], directory)) &&
+        (await succeeds(["commit", "--quiet", "--message", INITIAL_COMMIT_MESSAGE], directory));
+    return committed ? "committed" : "uncommitted";
+}
+async function succeeds(args, directory) {
+    try {
+        await run("git", args, { cwd: directory });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/adapters/pnpm-install.js

@@ -0,0 +1,23 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { createInterface } from "node:readline";
+/** Runs `pnpm install` in `directory`, handing on each line it prints. */
+export async function installDependencies(directory, onLine) {
+    const child = spawn("pnpm", ["install"], {
+        cwd: directory,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: process.platform === "win32",
+    });
+    for (const output of [child.stdout, child.stderr]) {
+        createInterface({ input: output }).on("line", onLine);
+    }
+    const [code] = await once(child, "close").catch(rethrowMissingPnpm);
+    if (code !== 0)
+        throw new Error(`pnpm install exited with code ${code}.`);
+}
+function rethrowMissingPnpm(error) {
+    if (error.code === "ENOENT") {
+        throw new Error("pnpm is not installed. Run `corepack enable pnpm`, then `pnpm install`.");
+    }
+    throw error;
+}

package/dist/adapters/scaffold-dependencies.js

@@ -0,0 +1,5 @@
+import { FsProjectFiles } from "./fs-project-files.js";
+import { FsTemplateSource } from "./fs-template-source.js";
+export function dependenciesAt(root) {
+    return { templates: new FsTemplateSource(), files: new FsProjectFiles(root) };
+}

package/dist/application/workspace-answers.js

@@ -0,0 +1,83 @@
+import { parsePackageName } from "../domain/app-spec.js";
+export class CancelledError extends Error {
+}
+/** Answers every question with its fallback: for --yes and anywhere that is not a terminal. */
+export const DEFAULT_ANSWERS = {
+    text: async (question) => question.fallback,
+    select: async (question) => question.fallback,
+};
+export const RECOMMENDED = {
+    platforms: "mobile-web",
+    tenantCode: "public-example",
+    baseUrl: "https://api.sandbox.ovok.com",
+};
+const NAME_QUESTION = {
+    message: "What is your project named?",
+    fallback: "ovok-app",
+    validate: (answer) => reasonRefused(() => parsePackageName(answer)),
+};
+const SETUP_QUESTION = {
+    message: "Use the recommended setup?",
+    options: [
+        {
+            value: "recommended",
+            label: "Yes, use the recommended setup",
+            hint: "web and mobile apps, iOS and Android, the Ovok sandbox",
+        },
+        { value: "customise", label: "No, customise it" },
+    ],
+    fallback: "recommended",
+};
+const PLATFORMS_QUESTION = {
+    message: "Which apps should it start with?",
+    options: [
+        { value: "mobile-web", label: "Web and mobile", hint: "apps/web and apps/mobile" },
+        { value: "web", label: "Web", hint: "Vite and React" },
+        { value: "mobile", label: "Mobile", hint: "Expo" },
+    ],
+    fallback: RECOMMENDED.platforms,
+};
+const TYPE_QUESTION = {
+    message: "Which mobile platforms?",
+    options: [
+        { value: null, label: "iOS and Android" },
+        { value: "ios", label: "iOS" },
+        { value: "android", label: "Android" },
+    ],
+    fallback: null,
+};
+const TENANT_QUESTION = {
+    message: "Which Ovok tenant code?",
+    fallback: RECOMMENDED.tenantCode,
+    validate: (answer) => (answer.trim() === "" ? "Enter a tenant code." : null),
+};
+const BASE_URL_QUESTION = {
+    message: "Which Ovok API URL?",
+    fallback: RECOMMENDED.baseUrl,
+    validate: (answer) => URL.canParse(answer) ? null : `Enter a URL such as ${RECOMMENDED.baseUrl}.`,
+};
+/** Asks only what no flag answered; after the recommended setup, only the name. */
+export async function answersFor(flags, prompt) {
+    const name = parsePackageName(flags.name ?? (await prompt.text(NAME_QUESTION)));
+    const ask = (await customises(flags, prompt)) ? prompt : DEFAULT_ANSWERS;
+    const platforms = flags.platforms ?? (await ask.select(PLATFORMS_QUESTION));
+    const type = flags.type ?? (platforms === "web" ? null : await ask.select(TYPE_QUESTION));
+    const tenantCode = flags.tenantCode ?? (await ask.text(TENANT_QUESTION));
+    const baseUrl = (flags.baseUrl ?? (await ask.text(BASE_URL_QUESTION))).replace(/\/+$/, "");
+    return { name, platforms, type, tenantCode, baseUrl };
+}
+/** A setup flag means the person is choosing already, so the rest is asked rather than assumed. */
+async function customises(flags, prompt) {
+    const setupFlags = [flags.platforms, flags.type, flags.tenantCode, flags.baseUrl];
+    return (setupFlags.some((flag) => flag !== null) ||
+        (await prompt.select(SETUP_QUESTION)) === "customise");
+}
+function reasonRefused(check) {
+    try {
+        check();
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}

package/dist/commands/create.js

@@ -0,0 +1,59 @@
+import { resolve } from "node:path";
+import { intro, log, note, outro, taskLog } from "@clack/prompts";
+import { initialiseGitRepository } from "../adapters/git-repository.js";
+import { installDependencies } from "../adapters/pnpm-install.js";
+import { dependenciesAt } from "../adapters/scaffold-dependencies.js";
+import { createWorkspace } from "../application/create-workspace.js";
+import { answersFor } from "../application/workspace-answers.js";
+import { startingApps } from "../domain/app-spec.js";
+const INSTALL_LOG_LINES = 6;
+const DOCS_URL = "https://docs.ovok.com";
+export async function scaffold(flags, prompt, version) {
+    intro(`create-ovok ${version}`);
+    const answers = await answersFor(flags, prompt);
+    const directory = resolve(answers.name);
+    const apps = startingApps(answers.platforms, answers.type);
+    await createWorkspace({
+        name: answers.name,
+        baseUrl: answers.baseUrl,
+        tenantCode: answers.tenantCode,
+        createOvokVersion: version,
+        apps,
+    }, dependenciesAt(directory));
+    const folders = apps.map((app) => `apps/${app.name}`).join(" and ");
+    log.success(`Created ${answers.name} with ${folders} in ${directory}.`);
+    return { name: answers.name, directory };
+}
+/** A failed install leaves the workspace in place; the next steps then include the install. */
+export async function install(workspace) {
+    const progress = taskLog({
+        title: "Installing dependencies with pnpm",
+        limit: INSTALL_LOG_LINES,
+    });
+    try {
+        await installDependencies(workspace.directory, (line) => progress.message(line));
+        progress.success("Installed dependencies.");
+        return "installed";
+    }
+    catch (error) {
+        progress.error(`Could not install dependencies: ${messageOf(error)}`, { showLog: true });
+        return "failed";
+    }
+}
+const GIT_REPORTS = {
+    committed: () => log.success("Initialised a git repository with a first commit."),
+    uncommitted: () => log.warn("Initialised a git repository; commit the files yourself once git knows your name."),
+    "inside-repository": () => log.info("Skipped git: the folder is inside a repository already."),
+    unavailable: () => log.warn("Skipped git: git is not installed."),
+};
+export async function initialiseGit(workspace) {
+    GIT_REPORTS[await initialiseGitRepository(workspace.directory)]();
+}
+export function showNextSteps(workspace, installation) {
+    const install = installation === "installed" ? [] : ["pnpm install"];
+    note([`cd ${workspace.name}`, ...install, "pnpm dev"].join("\n"), "Next steps");
+    outro(`Add an app with pnpm turbo gen app. Docs: ${DOCS_URL}`);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/main.js

@@ -1,23 +1,51 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
 import { parseArgs } from "node:util";
+import { cancel } from "@clack/prompts";
+import { ClackPrompt } from "./adapters/clack-prompt.js";
 import { FsProjectFiles } from "./adapters/fs-project-files.js";
-import { FsTemplateSource } from "./adapters/fs-template-source.js";
-import { TerminalPrompt } from "./adapters/terminal-prompt.js";
+import { dependenciesAt } from "./adapters/scaffold-dependencies.js";
 import { addApp, addPackage } from "./application/add-app.js";
-import { createWorkspace } from "./application/create-workspace.js";
 import { refreshAgentRules } from "./application/refresh-agent-rules.js";
-import { MOBILE_OSES, osFor, PLATFORMS, parseChoice, parsePackageName, STARTING_PLATFORMS, startingApps, } from "./domain/app-spec.js";
+import { CancelledError, DEFAULT_ANSWERS, RECOMMENDED, } from "./application/workspace-answers.js";
+import { initialiseGit, install, scaffold, showNextSteps } from "./commands/create.js";
+import { MOBILE_OSES, osFor, PLATFORMS, parseChoice, parsePackageName, STARTING_PLATFORMS, } from "./domain/app-spec.js";
 const EXIT_FAILURE = 1;
-const DEFAULT_BASE_URL = "https://api.sandbox.ovok.com";
-const DEFAULT_TENANT_CODE = "public-example";
+const EXIT_CANCELLED = 130;
 const OPTIONS = {
     platform: { type: "string" },
     type: { type: "string" },
     tenant: { type: "string" },
     "base-url": { type: "string" },
+    yes: { type: "boolean", short: "y" },
+    "skip-install": { type: "boolean" },
+    "disable-git": { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
 };
+const USAGE = `Usage: pnpm create ovok [name] [options]
+
+Creates a Turborepo with Ovok web and mobile apps, installs it and makes its first commit.
+Flags answer their questions; the rest are asked, or take the recommended setup with --yes.
+
+Options:
+  --platform <web|mobile|mobile-web>  The apps to start with
+  --type <ios|android>                Build the mobile app for one platform only
+  --tenant <code>                     Ovok tenant code (recommended: ${RECOMMENDED.tenantCode})
+  --base-url <url>                    Ovok API URL (recommended: ${RECOMMENDED.baseUrl})
+  -y, --yes                           Take the recommended setup for every unanswered question
+  --skip-install                      Do not run pnpm install
+  --disable-git                       Do not create a git repository
+  -h, --help                          Show this help
+  -v, --version                       Show the create-ovok version
+
+Inside a workspace (pnpm turbo gen runs these):
+  add <name> --platform web|mobile [--type ios|android]
+  add-package <name>
+  agents                              Refresh the Ovok rules in every AGENTS.md`;
+function parse(argv) {
+    return parseArgs({ args: argv, allowPositionals: true, options: OPTIONS });
+}
 const SUBCOMMANDS = {
     add: async ([name], values) => {
         const platform = parseChoice(values.platform ?? "", PLATFORMS, "--platform");
@@ -37,42 +65,44 @@ const SUBCOMMANDS = {
     },
 };
 async function main(argv) {
-    const { values, positionals } = parseArgs({
-        args: argv,
-        allowPositionals: true,
-        options: OPTIONS,
-    });
+    const { values, positionals } = parse(argv);
+    if (values.help)
+        return console.log(USAGE);
+    if (values.version)
+        return console.log(await ownVersion());
     const [first, ...rest] = positionals;
     const subcommand = first === undefined ? undefined : SUBCOMMANDS[first];
     if (subcommand === undefined)
-        return create(first, values);
+        return create(first ?? null, values);
     return subcommand(rest, values);
 }
-async function create(nameArgument, values) {
-    const prompt = new TerminalPrompt();
-    const name = parsePackageName(nameArgument ?? (await prompt.ask("Project name", "ovok-app")));
-    const platforms = values.platform === undefined
-        ? await prompt.choose("Platforms", STARTING_PLATFORMS, "mobile-web")
-        : parseChoice(values.platform, STARTING_PLATFORMS, "--platform");
-    const apps = startingApps(platforms, typeOf(values));
-    const directory = resolve(name);
-    await createWorkspace({
+async function create(name, values) {
+    const workspace = await scaffold(setupFlagsOf(name, values), promptFor(values), await ownVersion());
+    const installation = values["skip-install"] ? "skipped" : await install(workspace);
+    if (!values["disable-git"])
+        await initialiseGit(workspace);
+    showNextSteps(workspace, installation);
+    if (installation === "failed")
+        process.exitCode = EXIT_FAILURE;
+}
+function promptFor(values) {
+    const interactive = process.stdin.isTTY && process.stdout.isTTY && !values.yes;
+    return interactive ? new ClackPrompt() : DEFAULT_ANSWERS;
+}
+function setupFlagsOf(name, values) {
+    return {
         name,
-        baseUrl: (values["base-url"] ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
-        tenantCode: values.tenant ?? (await prompt.ask("Tenant code", DEFAULT_TENANT_CODE)),
-        createOvokVersion: await ownVersion(),
-        apps,
-    }, dependenciesAt(directory));
-    console.log(`Created ${name} with ${apps.map((app) => `apps/${app.name}`).join(" and ")}.\n`);
-    console.log(`  cd ${name}\n  pnpm install\n  pnpm dev\n`);
-    console.log("Add another app with `pnpm turbo gen app`.");
+        platforms: values.platform === undefined
+            ? null
+            : parseChoice(values.platform, STARTING_PLATFORMS, "--platform"),
+        type: typeOf(values),
+        tenantCode: values.tenant ?? null,
+        baseUrl: values["base-url"] ?? null,
+    };
 }
 function typeOf(values) {
     return values.type === undefined ? null : parseChoice(values.type, MOBILE_OSES, "--type");
 }
-function dependenciesAt(root) {
-    return { templates: new FsTemplateSource(), files: new FsProjectFiles(root) };
-}
 async function ownVersion() {
     const manifest = await readFile(new URL("../package.json", import.meta.url), "utf8");
     return JSON.parse(manifest).version;
@@ -81,6 +111,12 @@ try {
     await main(process.argv.slice(2));
 }
 catch (error) {
-    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
-    process.exitCode = EXIT_FAILURE;
+    if (error instanceof CancelledError) {
+        cancel(error.message);
+        process.exitCode = EXIT_CANCELLED;
+    }
+    else {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = EXIT_FAILURE;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ovok",
-  "version": "0.1.0-dev.13",
+  "version": "0.1.0-dev.21",
   "description": "Create a Turborepo with Ovok web and mobile apps, and add more apps through turbo gen.",
   "license": "MIT",
   "type": "module",
@@ -18,5 +18,8 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --test \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
   }
 }

package/dist/adapters/terminal-prompt.js

@@ -1,28 +0,0 @@
-import { createInterface } from "node:readline/promises";
-/** Asks only on a terminal; anywhere else a missing answer takes its default. */
-export class TerminalPrompt {
-    #interactive;
-    constructor(interactive = Boolean(process.stdin.isTTY)) {
-        this.#interactive = interactive;
-    }
-    async ask(question, fallback) {
-        if (!this.#interactive)
-            return fallback;
-        const prompt = createInterface({ input: process.stdin, output: process.stdout });
-        try {
-            const answer = (await prompt.question(`${question} (${fallback}): `)).trim();
-            return answer === "" ? fallback : answer;
-        }
-        finally {
-            prompt.close();
-        }
-    }
-    async choose(question, choices, fallback) {
-        for (;;) {
-            const answer = await this.ask(`${question} [${choices.join(" | ")}]`, fallback);
-            const choice = choices.find((candidate) => candidate === answer);
-            if (choice !== undefined)
-                return choice;
-        }
-    }
-}