create-ovok 0.0.0-stage → 0.1.0-dev.16

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# create-ovok
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```bash
+pnpm create ovok my-app
+```
+
+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:
+
+```bash
+pnpm turbo gen app       # add a web or mobile app
+pnpm turbo gen package   # add a shared package
+pnpm turbo gen agents    # rewrite the Ovok block of every AGENTS.md
+```
+
+Every app has an `AGENTS.md`, and a `CLAUDE.md` that imports it. The Ovok rules sit between
+`BEGIN:ovok-agent-rules` and `END:ovok-agent-rules`; the rest of each file is yours.

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/fs-project-files.js

@@ -0,0 +1,30 @@
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export class FsProjectFiles {
+    #root;
+    constructor(root) {
+        this.#root = root;
+    }
+    async exists(path) {
+        return access(join(this.#root, path)).then(() => true, () => false);
+    }
+    async read(path) {
+        return readFile(join(this.#root, path), "utf8").catch(missingAs(null));
+    }
+    async write(path, content) {
+        const absolute = join(this.#root, path);
+        await mkdir(dirname(absolute), { recursive: true });
+        await writeFile(absolute, content);
+    }
+    async directories(path) {
+        const entries = await readdir(join(this.#root, path), { withFileTypes: true }).catch(missingAs([]));
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+}
+function missingAs(fallback) {
+    return (error) => {
+        if (error.code === "ENOENT")
+            return fallback;
+        throw error;
+    };
+}

package/dist/adapters/fs-template-source.js

@@ -0,0 +1,25 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const TEMPLATES_DIRECTORY = fileURLToPath(new URL("../../templates/", import.meta.url));
+/** npm leaves `.gitignore` out of a published package, so templates carry it as `_gitignore`. */
+const PUBLISHED_NAMES = { _gitignore: ".gitignore" };
+export class FsTemplateSource {
+    async files(template) {
+        const root = join(TEMPLATES_DIRECTORY, template);
+        const entries = await readdir(root, { recursive: true, withFileTypes: true });
+        const files = entries.filter((entry) => entry.isFile());
+        return Promise.all(files.map(async (entry) => {
+            const absolute = join(entry.parentPath, entry.name);
+            return {
+                path: projectPathOf(relative(root, absolute)),
+                content: await readFile(absolute, "utf8"),
+            };
+        }));
+    }
+}
+function projectPathOf(templatePath) {
+    const segments = templatePath.split(sep);
+    const name = segments.pop() ?? "";
+    return [...segments, PUBLISHED_NAMES[name] ?? name].join("/");
+}

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/add-app.js

@@ -0,0 +1,50 @@
+import { appRulesBlock } from "../domain/agent-rules.js";
+import { bundleIdFor, MOBILE_OSES } from "../domain/app-spec.js";
+import { copyTemplate } from "./copy-template.js";
+export class NotAWorkspaceError extends Error {
+}
+export class AlreadyExistsError extends Error {
+}
+export async function addApp(app, deps) {
+    const workspace = await workspaceNameOf(deps.files);
+    const directory = await freeDirectory(`apps/${app.name}`, deps.files);
+    await copyTemplate(app.platform, directory, {
+        workspace,
+        folder: app.name,
+        bundleId: bundleIdFor(workspace, app.name),
+        platforms: app.os.map((os) => `"${os}"`).join(", "),
+        agentRules: appRulesBlock(app.platform),
+    }, deps);
+    if (app.platform === "mobile") {
+        await keepRunScriptsOf(app.os, `${directory}/package.json`, deps.files);
+    }
+    return directory;
+}
+export async function addPackage(name, deps) {
+    const workspace = await workspaceNameOf(deps.files);
+    const directory = await freeDirectory(`packages/${name}`, deps.files);
+    await copyTemplate("package", directory, { workspace, folder: name }, deps);
+    return directory;
+}
+async function workspaceNameOf(files) {
+    const manifest = await files.read("package.json");
+    const isWorkspace = manifest !== null && (await files.exists("pnpm-workspace.yaml"));
+    const name = isWorkspace ? JSON.parse(manifest).name : undefined;
+    if (typeof name !== "string") {
+        throw new NotAWorkspaceError("Run this at the root of a workspace made by create-ovok.");
+    }
+    return name;
+}
+async function freeDirectory(directory, files) {
+    if (await files.exists(directory))
+        throw new AlreadyExistsError(`${directory} already exists.`);
+    return directory;
+}
+/** Drops the run script of each OS the app leaves out, so `pnpm android` is not offered to an iOS-only app. */
+async function keepRunScriptsOf(os, path, files) {
+    const manifest = JSON.parse((await files.read(path)) ?? "{}");
+    for (const dropped of MOBILE_OSES.filter((candidate) => !os.includes(candidate))) {
+        delete manifest.scripts?.[dropped];
+    }
+    await files.write(path, `${JSON.stringify(manifest, null, 2)}\n`);
+}

package/dist/application/copy-template.js

@@ -0,0 +1,7 @@
+import { posix } from "node:path";
+import { renderTemplate } from "../domain/template-text.js";
+export async function copyTemplate(template, directory, variables, deps) {
+    for (const file of await deps.templates.files(template)) {
+        await deps.files.write(posix.join(directory, file.path), renderTemplate(file.content, variables));
+    }
+}

package/dist/application/create-workspace.js

@@ -0,0 +1,19 @@
+import { workspaceRulesBlock } from "../domain/agent-rules.js";
+import { AlreadyExistsError, addApp } from "./add-app.js";
+import { copyTemplate } from "./copy-template.js";
+export async function createWorkspace(spec, deps) {
+    if (await deps.files.exists("package.json")) {
+        throw new AlreadyExistsError("The folder already holds a project.");
+    }
+    await copyTemplate("workspace", "", {
+        workspace: spec.name,
+        baseUrl: spec.baseUrl,
+        tenantCode: spec.tenantCode,
+        createOvokVersion: spec.createOvokVersion,
+        agentRules: workspaceRulesBlock(),
+    }, deps);
+    const directories = [];
+    for (const app of spec.apps)
+        directories.push(await addApp(app, deps));
+    return directories;
+}

package/dist/application/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/application/refresh-agent-rules.js

@@ -0,0 +1,24 @@
+import { appRulesBlock, replaceRulesBlock, workspaceRulesBlock } from "../domain/agent-rules.js";
+import { PLATFORMS } from "../domain/app-spec.js";
+const AGENTS_FILE = "AGENTS.md";
+/** Rewrites the Ovok block of every AGENTS.md to this create-ovok's rules; the rest is the team's. */
+export async function refreshAgentRules(files) {
+    const refreshed = [await refresh(AGENTS_FILE, workspaceRulesBlock(), files)];
+    for (const app of await files.directories("apps")) {
+        const platform = await platformOf(`apps/${app}/package.json`, files);
+        if (platform !== null) {
+            refreshed.push(await refresh(`apps/${app}/${AGENTS_FILE}`, appRulesBlock(platform), files));
+        }
+    }
+    return refreshed;
+}
+async function refresh(path, block, files) {
+    await files.write(path, replaceRulesBlock((await files.read(path)) ?? "", block));
+    return path;
+}
+/** Apps made by create-ovok name their platform in package.json; other apps are left alone. */
+async function platformOf(path, files) {
+    const manifest = await files.read(path);
+    const platform = manifest === null ? undefined : JSON.parse(manifest)?.ovok?.platform;
+    return PLATFORMS.find((candidate) => candidate === platform) ?? null;
+}

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/domain/agent-rules.js

@@ -0,0 +1,43 @@
+export const RULES_BEGIN = "<!-- BEGIN:ovok-agent-rules -->";
+export const RULES_END = "<!-- END:ovok-agent-rules -->";
+const WORKSPACE_RULES = `## This is NOT the Ovok you know
+
+Your training data is out of date for Ovok. Before writing code that touches it, read the guide in
+\`node_modules/@ovok/core/docs/\` (web) or \`node_modules/@ovok/native/docs/\` (mobile), resolved
+from the app's own directory: they match the installed version. If that folder is missing, read
+https://docs.ovok.com/llms.txt instead. Platform concepts (FHIR, settings, Signals) are there too.
+
+- Check live data and settings with the \`ovok\` MCP server in \`.mcp.json\` instead of guessing.
+- Never evaluate vital-sign thresholds in app code: Signals decides alerts; you send or edit its rules.
+- Add apps and packages with \`pnpm turbo gen\`, never by copying a folder.`;
+const PLATFORM_RULES = {
+    web: `## Ovok in this web app
+
+- Vite and React on \`@ovok/core\`. Use the one \`Ovok\` client in \`src/ovok.ts\`; never create another.
+- \`OVOK_BASE_URL\` and \`OVOK_TENANT_CODE\` come from the root \`.env\` through \`vite.config.ts\`.
+  Only those two reach the browser; never widen that list, as everything in this app ships to users.`,
+    mobile: `## Ovok in this mobile app
+
+- Expo with a development build: Bluetooth needs native code, so Expo Go cannot run it. Use
+  \`pnpm ios\` or \`pnpm android\`.
+- Read \`node_modules/@ovok/native/docs/\` before touching devices or Bluetooth.
+- Use the one \`Ovok\` client in \`src/ovok.ts\`; its settings come from the root \`.env\` through
+  \`app.config.ts\`.`,
+};
+/** The block `create-ovok agents` owns: it rewrites what is between the markers and nothing else. */
+export function workspaceRulesBlock() {
+    return block(WORKSPACE_RULES);
+}
+export function appRulesBlock(platform) {
+    return block(PLATFORM_RULES[platform]);
+}
+export function replaceRulesBlock(document, replacement) {
+    const start = document.indexOf(RULES_BEGIN);
+    const end = document.indexOf(RULES_END, start);
+    if (start === -1 || end === -1)
+        return `${replacement}\n\n${document}`;
+    return document.slice(0, start) + replacement + document.slice(end + RULES_END.length);
+}
+function block(rules) {
+    return `${RULES_BEGIN}\n${rules}\n${RULES_END}`;
+}

package/dist/domain/app-spec.js

@@ -0,0 +1,46 @@
+export const PLATFORMS = ["web", "mobile"];
+export const MOBILE_OSES = ["ios", "android"];
+export const STARTING_PLATFORMS = ["web", "mobile", "mobile-web"];
+/** The npm rules for an unscoped name, which every app folder and workspace name follows. */
+const PACKAGE_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+const PACKAGE_NAME_MAX_LENGTH = 214;
+export class InvalidSpecError extends Error {
+}
+export function parsePackageName(raw) {
+    if (!PACKAGE_NAME.test(raw) || raw.length > PACKAGE_NAME_MAX_LENGTH) {
+        throw new InvalidSpecError(`"${raw}" is not a valid name: use lowercase letters, digits, ".", "_" and "-".`);
+    }
+    return raw;
+}
+export function parseChoice(raw, choices, flag) {
+    const choice = choices.find((candidate) => candidate === raw);
+    if (choice === undefined)
+        throw new InvalidSpecError(`${flag} is one of ${choices.join(", ")}.`);
+    return choice;
+}
+/** `--type` narrows a mobile app to one OS; on a web app it means nothing, so it is refused. */
+export function osFor(platform, type) {
+    if (platform === "web") {
+        if (type !== null)
+            throw new InvalidSpecError("--type only applies to mobile apps.");
+        return [];
+    }
+    return type === null ? MOBILE_OSES : [type];
+}
+/** A reverse-DNS id both stores accept: letters and digits per segment, never a leading digit. */
+export function bundleIdFor(workspace, app) {
+    const segment = (raw) => {
+        const cleaned = raw.toLowerCase().replace(/[^a-z0-9]/g, "");
+        return /^[a-z]/.test(cleaned) ? cleaned : `app${cleaned}`;
+    };
+    return ["com", "example", segment(workspace), segment(app)].join(".");
+}
+export function startingApps(platforms, type) {
+    const web = { name: "web", platform: "web", os: [] };
+    const mobile = { name: "mobile", platform: "mobile", os: osFor("mobile", type) };
+    if (platforms === "web")
+        return [{ ...web, os: osFor("web", type) }];
+    if (platforms === "mobile")
+        return [mobile];
+    return [web, mobile];
+}

package/dist/domain/template-text.js

@@ -0,0 +1,12 @@
+const PLACEHOLDER = /\{\{(\w+)\}\}/g;
+export class MissingVariableError extends Error {
+}
+/** Fills every `{{name}}`; a placeholder without a value is a template bug, so it fails loudly. */
+export function renderTemplate(text, variables) {
+    return text.replace(PLACEHOLDER, (_match, name) => {
+        const value = variables[name];
+        if (value === undefined)
+            throw new MissingVariableError(`The template needs "${name}".`);
+        return value;
+    });
+}

package/dist/main.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+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 { dependenciesAt } from "./adapters/scaffold-dependencies.js";
+import { addApp, addPackage } from "./application/add-app.js";
+import { refreshAgentRules } from "./application/refresh-agent-rules.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 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");
+        const app = {
+            name: parsePackageName(name ?? ""),
+            platform,
+            os: osFor(platform, typeOf(values)),
+        };
+        console.log(`Added ${await addApp(app, dependenciesAt(process.cwd()))}.`);
+    },
+    "add-package": async ([name]) => {
+        console.log(`Added ${await addPackage(parsePackageName(name ?? ""), dependenciesAt(process.cwd()))}.`);
+    },
+    agents: async () => {
+        const refreshed = await refreshAgentRules(new FsProjectFiles(process.cwd()));
+        console.log(`Refreshed the Ovok rules in ${refreshed.join(", ")}.`);
+    },
+};
+async function main(argv) {
+    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 ?? null, values);
+    return subcommand(rest, values);
+}
+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,
+        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");
+}
+async function ownVersion() {
+    const manifest = await readFile(new URL("../package.json", import.meta.url), "utf8");
+    return JSON.parse(manifest).version;
+}
+try {
+    await main(process.argv.slice(2));
+}
+catch (error) {
+    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,25 @@
 {
   "name": "create-ovok",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-dev.16",
+  "description": "Create a Turborepo with Ovok web and mobile apps, and add more apps through turbo gen.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-ovok": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  }
+}

package/templates/mobile/AGENTS.md

@@ -0,0 +1,5 @@
+# {{folder}}
+
+{{agentRules}}
+
+Start the development server with `pnpm dev` here, after a first `pnpm ios` or `pnpm android` build.

package/templates/mobile/App.tsx

@@ -0,0 +1,50 @@
+import { useState } from "react";
+import { Button, StyleSheet, Text, TextInput, View } from "react-native";
+import { ovok } from "./src/ovok";
+
+export default function App() {
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [status, setStatus] = useState("Sign in with a patient account.");
+
+  async function signIn() {
+    try {
+      const result = await ovok.auth.login({ profileType: "Patient", email, password });
+      setStatus(result.status === "signed-in" ? "Signed in." : "This account needs a second factor.");
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  return (
+    <View style={styles.screen}>
+      <Text style={styles.status} accessibilityLiveRegion="polite">
+        {status}
+      </Text>
+      <TextInput
+        style={styles.input}
+        placeholder="Email"
+        autoCapitalize="none"
+        autoComplete="email"
+        keyboardType="email-address"
+        value={email}
+        onChangeText={setEmail}
+      />
+      <TextInput
+        style={styles.input}
+        placeholder="Password"
+        autoComplete="current-password"
+        secureTextEntry
+        value={password}
+        onChangeText={setPassword}
+      />
+      <Button title="Sign in" onPress={signIn} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: { flex: 1, justifyContent: "center", gap: 12, padding: 24 },
+  status: { fontSize: 16 },
+  input: { borderWidth: 1, borderRadius: 8, padding: 12 },
+});

package/templates/mobile/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/mobile/app.config.ts

@@ -0,0 +1,30 @@
+import type { ExpoConfig } from "expo/config";
+
+process.loadEnvFile("../../.env");
+
+const config: ExpoConfig = {
+  name: "{{folder}}",
+  slug: "{{workspace}}-{{folder}}",
+  version: "1.0.0",
+  orientation: "portrait",
+  platforms: [{{platforms}}],
+  ios: { bundleIdentifier: "{{bundleId}}" },
+  android: { package: "{{bundleId}}" },
+  plugins: [
+    "expo-secure-store",
+    [
+      "react-native-ble-plx",
+      {
+        isBackgroundEnabled: false,
+        bluetoothAlwaysPermission: "Connect to your measurement devices to receive readings.",
+      },
+    ],
+    ["react-native-permissions", { iosPermissions: ["Bluetooth"] }],
+  ],
+  extra: {
+    ovokBaseUrl: process.env.OVOK_BASE_URL,
+    ovokTenantCode: process.env.OVOK_TENANT_CODE,
+  },
+};
+
+export default config;

package/templates/mobile/index.js

@@ -0,0 +1,8 @@
+import { registerRootComponent } from "expo";
+import { polyfillWebCrypto } from "expo-standard-web-crypto";
+
+polyfillWebCrypto();
+
+// The Ovok client's PKCE helpers need web crypto before they load.
+const App = require("./App").default;
+registerRootComponent(App);

package/templates/mobile/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@{{workspace}}/{{folder}}",
+  "private": true,
+  "main": "index.js",
+  "ovok": {
+    "platform": "mobile"
+  },
+  "scripts": {
+    "dev": "expo start --dev-client",
+    "ios": "expo run:ios",
+    "android": "expo run:android",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ovok/core": "^0.4.49-rc.4",
+    "@ovok/native": "^1.16.1-rc.3",
+    "expo": "~57.0.31",
+    "expo-constants": "~57.0.22",
+    "expo-dev-client": "~57.0.20",
+    "expo-secure-store": "~57.0.4",
+    "expo-standard-web-crypto": "^57.0.3",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "react-native-ble-plx": "^3.5.1",
+    "react-native-permissions": "^5.6.2"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.0",
+    "typescript": "~6.0.3"
+  }
+}

package/templates/mobile/src/ovok.ts

@@ -0,0 +1,12 @@
+import { Ovok } from "@ovok/core/next";
+import Constants from "expo-constants";
+
+type OvokExtra = { ovokBaseUrl: string; ovokTenantCode: string };
+
+const extra = Constants.expoConfig?.extra as OvokExtra;
+
+export const ovok = new Ovok({
+  baseUrl: extra.ovokBaseUrl,
+  tenantCode: extra.ovokTenantCode,
+  fhirPath: "/fhir/R4/",
+});

package/templates/mobile/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "exclude": ["node_modules", "ios", "android"]
+}

package/templates/package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@{{workspace}}/{{folder}}",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}

package/templates/package/src/index.ts

@@ -0,0 +1 @@
+export {};

package/templates/package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/templates/web/AGENTS.md

@@ -0,0 +1,5 @@
+# {{folder}}
+
+{{agentRules}}
+
+Run it with `pnpm dev` here, or `pnpm turbo run dev --filter @{{workspace}}/{{folder}}` from the root.

package/templates/web/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{folder}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/web/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@{{workspace}}/{{folder}}",
+  "private": true,
+  "type": "module",
+  "ovok": {
+    "platform": "web"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@ovok/core": "^0.4.49-rc.4",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@medplum/fhirtypes": "^5.2.11",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4"
+  }
+}

package/templates/web/src/App.tsx

@@ -0,0 +1,66 @@
+import type { Patient } from "@medplum/fhirtypes";
+import { type FormEvent, useState } from "react";
+import { ovok } from "./ovok";
+
+const PATIENTS_SHOWN = 10;
+
+export function App() {
+  const [patients, setPatients] = useState<Patient[] | null>(null);
+  const [problem, setProblem] = useState<string | null>(null);
+
+  async function signIn(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const form = new FormData(event.currentTarget);
+    setProblem(null);
+    try {
+      const result = await ovok.auth.login({
+        profileType: "Practitioner",
+        email: String(form.get("email")),
+        password: String(form.get("password")),
+      });
+      if (result.status !== "signed-in") {
+        setProblem("This account needs a second factor: finish with ovok.auth.verifyMfa.");
+        return;
+      }
+      const page = await ovok.fhir.search("Patient", { _count: String(PATIENTS_SHOWN) });
+      setPatients(page.data);
+    } catch (error) {
+      setProblem(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  if (patients !== null) {
+    return (
+      <main>
+        <h1>Patients</h1>
+        <ul>
+          {patients.map((patient) => (
+            <li key={patient.id}>{nameOf(patient)}</li>
+          ))}
+        </ul>
+      </main>
+    );
+  }
+
+  return (
+    <main>
+      <h1>Sign in</h1>
+      <form onSubmit={signIn}>
+        <label>
+          Email <input name="email" type="email" autoComplete="username" required />
+        </label>
+        <label>
+          Password <input name="password" type="password" autoComplete="current-password" required />
+        </label>
+        <button type="submit">Sign in</button>
+        {problem !== null && <p role="alert">{problem}</p>}
+      </form>
+    </main>
+  );
+}
+
+function nameOf(patient: Patient): string {
+  const name = patient.name?.[0];
+  const parts = [...(name?.given ?? []), name?.family].filter((part) => part !== undefined);
+  return parts.length > 0 ? parts.join(" ") : (patient.id ?? "Unnamed patient");
+}

package/templates/web/src/env.d.ts

@@ -0,0 +1,4 @@
+interface ImportMetaEnv {
+  readonly OVOK_BASE_URL: string;
+  readonly OVOK_TENANT_CODE: string;
+}

package/templates/web/src/main.tsx

@@ -0,0 +1,12 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+const root = document.getElementById("root");
+if (root === null) throw new Error("index.html has no #root element.");
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/web/src/ovok.ts

@@ -0,0 +1,7 @@
+import { Ovok } from "@ovok/core/next";
+
+export const ovok = new Ovok({
+  baseUrl: import.meta.env.OVOK_BASE_URL,
+  tenantCode: import.meta.env.OVOK_TENANT_CODE,
+  fhirPath: "/fhir/R4/",
+});

package/templates/web/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["es2022", "dom", "dom.iterable"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "types": ["vite/client"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/web/vite.config.ts

@@ -0,0 +1,16 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig, loadEnv } from "vite";
+
+const WORKSPACE_ROOT = "../..";
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, WORKSPACE_ROOT, "OVOK_");
+  return {
+    plugins: [react()],
+    // Everything here ships to the browser, so it names each variable rather than a prefix.
+    define: {
+      "import.meta.env.OVOK_BASE_URL": JSON.stringify(env.OVOK_BASE_URL),
+      "import.meta.env.OVOK_TENANT_CODE": JSON.stringify(env.OVOK_TENANT_CODE),
+    },
+  };
+});

package/templates/workspace/.env

@@ -0,0 +1,2 @@
+OVOK_BASE_URL={{baseUrl}}
+OVOK_TENANT_CODE={{tenantCode}}

package/templates/workspace/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "ovok": {
+      "type": "http",
+      "url": "{{baseUrl}}/mcp"
+    }
+  }
+}

package/templates/workspace/AGENTS.md

@@ -0,0 +1,11 @@
+# {{workspace}}
+
+{{agentRules}}
+
+## This repository
+
+- A Turborepo on pnpm workspaces: apps in `apps/`, shared code in `packages/`.
+- `pnpm dev` runs every app; `pnpm turbo run dev --filter <app>` runs one.
+- `OVOK_BASE_URL` and `OVOK_TENANT_CODE` live in the root `.env`, which every app reads.
+- `pnpm turbo gen app` adds a web or mobile app and `pnpm turbo gen package` a shared package.
+  `pnpm turbo gen agents` rewrites the Ovok block of every AGENTS.md after `create-ovok` updates.

package/templates/workspace/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/workspace/README.md

@@ -0,0 +1,11 @@
+# {{workspace}}
+
+An Ovok workspace made with `create-ovok`.
+
+```bash
+pnpm install
+pnpm dev
+```
+
+- Apps live in `apps/`. Add one with `pnpm turbo gen app`, a shared package with `pnpm turbo gen package`.
+- The Ovok API and tenant are set in `.env`.

package/templates/workspace/_gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.turbo/
+.expo/
+ios/
+android/
+*.tsbuildinfo
+.env.local
+.DS_Store

package/templates/workspace/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "{{workspace}}",
+  "private": true,
+  "packageManager": "pnpm@10.8.0",
+  "scripts": {
+    "dev": "turbo run dev",
+    "build": "turbo run build",
+    "typecheck": "turbo run typecheck"
+  },
+  "devDependencies": {
+    "@turbo/gen": "2.11.10",
+    "create-ovok": "^{{createOvokVersion}}",
+    "turbo": "2.11.10"
+  }
+}

package/templates/workspace/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+packages:
+  - apps/*
+  - packages/*
+onlyBuiltDependencies:
+  - esbuild

package/templates/workspace/turbo/generators/config.ts

@@ -0,0 +1,57 @@
+import { execFileSync } from "node:child_process";
+import type { PlopTypes } from "@turbo/gen";
+
+type AppAnswers = { name: string; platform: "web" | "mobile"; os?: "both" | "ios" | "android" };
+
+/** Each generator hands off to create-ovok, so `turbo gen` and `pnpm create ovok` share one set of templates. */
+function createOvok(args: string[]): void {
+  execFileSync("pnpm", ["exec", "create-ovok", ...args], { stdio: "inherit" });
+}
+
+export default function generator(plop: PlopTypes.NodePlopAPI): void {
+  plop.setGenerator("app", {
+    description: "Add an Ovok web or mobile app to apps/",
+    prompts: [
+      { type: "input", name: "name", message: "App name (its folder under apps/)" },
+      { type: "list", name: "platform", message: "Platform", choices: ["web", "mobile"] },
+      {
+        type: "list",
+        name: "os",
+        message: "Mobile OS",
+        choices: ["both", "ios", "android"],
+        when: (answers: AppAnswers) => answers.platform === "mobile",
+      },
+    ],
+    actions: [
+      (answers) => {
+        const { name, platform, os } = answers as AppAnswers;
+        const type = os === undefined || os === "both" ? [] : ["--type", os];
+        createOvok(["add", name, "--platform", platform, ...type]);
+        return `Added apps/${name}`;
+      },
+    ],
+  });
+
+  plop.setGenerator("package", {
+    description: "Add a shared package to packages/",
+    prompts: [{ type: "input", name: "name", message: "Package name (its folder under packages/)" }],
+    actions: [
+      (answers) => {
+        const { name } = answers as { name: string };
+        createOvok(["add-package", name]);
+        return `Added packages/${name}`;
+      },
+    ],
+  });
+
+  plop.setGenerator("agents", {
+    description: "Rewrite the Ovok block of every AGENTS.md",
+    prompts: [],
+    actions: [
+      () => {
+        createOvok(["agents"]);
+        return "Refreshed the Ovok rules";
+      },
+    ],
+  });
+}

package/templates/workspace/turbo.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://turborepo.com/schema.json",
+  "globalDependencies": [".env"],
+  "globalEnv": ["OVOK_BASE_URL", "OVOK_TENANT_CODE"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "typecheck": {
+      "dependsOn": ["^typecheck"]
+    }
+  }
+}