create-flowdular 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flowdular contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# create-flowdular
+
+Scaffold a Flowdular application.
+
+```bash
+npm create flowdular@latest my-app
+```
+
+`pnpm create flowdular my-app` and `yarn create flowdular my-app` resolve to the
+same package. `npx create-flowdular@latest my-app` runs it directly.
+
+It creates the directory, copies the template (the platform plus one example
+module), rewrites the package name, generates this app's secret keys into
+`.env`, installs the pnpm workspace dependencies, and
+makes the first commit.
+
+## Options
+
+| Option                  | Default   | Effect                                      |
+| ----------------------- | --------- | ------------------------------------------- |
+| `-t, --template <name>` | `default` | Template to copy                            |
+| `--pm <manager>`        | `pnpm`    | Use `pnpm` for this template                |
+| `--no-install`          | installs  | Skip dependency installation                |
+| `--no-git`              | commits   | Skip repository initialization              |
+| `-f, --force`           | refuses   | Scaffold into a directory that is not empty |
+| `-h, --help`            |           | Show usage                                  |
+| `-v, --version`         |           | Show the version                            |
+
+## What it generates
+
+Local development runs on embedded PostgreSQL, so a new app needs no database
+server and no connection string. The generated `.env` sets
+`FD_DATABASE_ADAPTER=pglite` and one fresh base64 encoded 32 byte key per
+secret: `FD_AGENT_CREDENTIAL_KEY`, `FD_AGENT_RUN_GRANT_KEY`,
+`FD_WORKFLOWS_PAYLOAD_KEY`, `FD_WORKFLOWS_CURSOR_KEY` and `FD_AUTH_MFA_KEY`. The
+keys differ on every run and never leave the machine.
+
+The scaffolder makes no network call of its own; the only one is the package
+manager install, which `--no-install` skips. It collects nothing.
+
+## After it finishes
+
+```bash
+cd my-app
+pnpm flowdular setup quick --apply --confirm reset-local-auth
+pnpm dev
+```
+
+Then open <http://localhost:4310>.
+
+`npm create` launches the generator; the generated application uses pnpm workspaces. If pnpm is missing, the generator runs the pinned pnpm version through `npm exec`. The only Flowdular dependencies published to npm are `@flowdular/sdk`, `flowdular` and `create-flowdular`. UI is available through `@flowdular/sdk/ui` and `@flowdular/sdk/ui/styles`.

package/dist/bin.js

@@ -0,0 +1,526 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { relative as relative2, resolve as resolve3 } from "node:path";
+
+// src/name.ts
+var MAX_LENGTH = 214;
+var NAME_PATTERN = /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+var RESERVED = /* @__PURE__ */ new Set(["node_modules", "favicon.ico"]);
+function checkProjectName(name) {
+  if (name.length === 0) return { valid: false, reason: "name is empty" };
+  if (name.trim() !== name) {
+    return { valid: false, reason: "name has leading or trailing whitespace" };
+  }
+  if (name.length > MAX_LENGTH) {
+    return {
+      valid: false,
+      reason: `name is longer than ${String(MAX_LENGTH)} characters`
+    };
+  }
+  if (name.startsWith(".") || name.startsWith("_")) {
+    return { valid: false, reason: "name starts with a dot or an underscore" };
+  }
+  if (name !== name.toLowerCase()) {
+    return { valid: false, reason: "name contains uppercase letters" };
+  }
+  if (RESERVED.has(name)) {
+    return { valid: false, reason: `"${name}" is a reserved npm name` };
+  }
+  if (!NAME_PATTERN.test(name)) {
+    return {
+      valid: false,
+      reason: "name may contain only lowercase letters, digits, and the characters - . _ ~"
+    };
+  }
+  return { valid: true };
+}
+function checkTargetPath(target) {
+  if (target.length === 0) return { valid: false, reason: "path is empty" };
+  if (target.trim() !== target) {
+    return { valid: false, reason: "path has leading or trailing whitespace" };
+  }
+  const segments = target.split(/[\\/]+/);
+  if (segments.includes("..")) {
+    return { valid: false, reason: "path escapes the current directory" };
+  }
+  if (target.includes("\0")) {
+    return { valid: false, reason: "path contains a null byte" };
+  }
+  return { valid: true };
+}
+
+// src/args.ts
+var PACKAGE_MANAGERS = ["pnpm", "npm", "yarn"];
+var ArgumentError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ArgumentError";
+  }
+};
+function isPackageManager(value) {
+  return PACKAGE_MANAGERS.includes(value);
+}
+function valueOf(flag, inline, next) {
+  if (inline !== void 0) {
+    if (inline.length === 0) throw new ArgumentError(`${flag} needs a value.`);
+    return { value: inline, consumedNext: false };
+  }
+  if (next === void 0 || next.startsWith("-")) {
+    throw new ArgumentError(`${flag} needs a value.`);
+  }
+  return { value: next, consumedNext: true };
+}
+function parseArguments(argv) {
+  let target;
+  let template = "default";
+  let packageManager;
+  let install = true;
+  let git2 = true;
+  let force = false;
+  let help = false;
+  let version = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    const separator = argument.indexOf("=");
+    const flag = separator === -1 ? argument : argument.slice(0, separator);
+    const inline = separator === -1 ? void 0 : argument.slice(separator + 1);
+    switch (flag) {
+      case "--help":
+      case "-h":
+        help = true;
+        continue;
+      case "--version":
+      case "-v":
+        version = true;
+        continue;
+      case "--no-install":
+        install = false;
+        continue;
+      case "--no-git":
+        git2 = false;
+        continue;
+      case "--force":
+      case "-f":
+        force = true;
+        continue;
+      case "--template":
+      case "-t": {
+        const parsed = valueOf(flag, inline, argv[index + 1]);
+        if (!/^[a-z][a-z0-9-]*$/.test(parsed.value)) {
+          throw new ArgumentError(
+            `"${parsed.value}" is not a template name; use lowercase letters, digits and hyphens.`
+          );
+        }
+        template = parsed.value;
+        if (parsed.consumedNext) index += 1;
+        continue;
+      }
+      case "--pm": {
+        const parsed = valueOf(flag, inline, argv[index + 1]);
+        if (!isPackageManager(parsed.value)) {
+          throw new ArgumentError(
+            `--pm must be one of ${PACKAGE_MANAGERS.join(", ")}.`
+          );
+        }
+        packageManager = parsed.value;
+        if (parsed.consumedNext) index += 1;
+        continue;
+      }
+      default:
+        break;
+    }
+    if (argument.startsWith("-")) {
+      throw new ArgumentError(`Unknown option "${argument}".`);
+    }
+    if (target !== void 0) {
+      throw new ArgumentError(
+        `Unexpected argument "${argument}"; the directory is given once.`
+      );
+    }
+    target = argument;
+  }
+  if (help || version) {
+    return {
+      target: target ?? "",
+      template,
+      ...packageManager ? { packageManager } : {},
+      install,
+      git: git2,
+      force,
+      help,
+      version
+    };
+  }
+  if (target === void 0) {
+    throw new ArgumentError(
+      "Name the directory to create, for example: create-flowdular my-app"
+    );
+  }
+  const path = checkTargetPath(target);
+  if (!path.valid) {
+    throw new ArgumentError(
+      `"${target}" is not a usable directory: ${path.reason}.`
+    );
+  }
+  return {
+    target,
+    template,
+    ...packageManager ? { packageManager } : {},
+    install,
+    git: git2,
+    force,
+    help,
+    version
+  };
+}
+
+// src/git.ts
+import { spawnSync } from "node:child_process";
+function git(directory, ...arguments_) {
+  const result = spawnSync("git", arguments_, {
+    cwd: directory,
+    stdio: "ignore"
+  });
+  if (result.error) return { ok: false, reason: "git is not available" };
+  if (result.status !== 0) {
+    return { ok: false, reason: `git ${arguments_[0]} failed` };
+  }
+  return { ok: true };
+}
+function initializeRepository(directory) {
+  const initialized = git(directory, "init", "-b", "main");
+  if (!initialized.ok) return initialized;
+  const staged = git(directory, "add", "-A");
+  if (!staged.ok) return staged;
+  const committed = git(
+    directory,
+    "commit",
+    "-m",
+    "chore: scaffold Flowdular app"
+  );
+  if (!committed.ok) {
+    return {
+      ok: false,
+      reason: "the repository was created but the first commit failed, most likely because git has no user.name and user.email"
+    };
+  }
+  return { ok: true };
+}
+
+// src/pm.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+function detectPackageManager(_userAgent) {
+  return "pnpm";
+}
+function installDependencies(packageManager, directory) {
+  let result = spawnSync2(packageManager, ["install"], {
+    cwd: directory,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  if (packageManager === "pnpm" && result.error?.code === "ENOENT") {
+    result = spawnSync2(
+      "npm",
+      ["exec", "--yes", "--package=pnpm@11.17.0", "--", "pnpm", "install"],
+      {
+        cwd: directory,
+        stdio: "inherit",
+        shell: process.platform === "win32"
+      }
+    );
+  }
+  if (result.error) {
+    return { ok: false, reason: `${packageManager} could not be started` };
+  }
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      reason: `${packageManager} install exited with code ${String(result.status)}`
+    };
+  }
+  return { ok: true };
+}
+
+// src/report.ts
+var DEV_URL = "http://localhost:4310";
+function runScript(packageManager, script, ...arguments_) {
+  if (arguments_.length === 0) {
+    return packageManager === "npm" ? `npm run ${script}` : `${packageManager} ${script}`;
+  }
+  const tail = arguments_.join(" ");
+  return packageManager === "npm" ? `npm run ${script} -- ${tail}` : `${packageManager} ${script} ${tail}`;
+}
+function nextSteps(input) {
+  return [
+    `cd ${input.directory}`,
+    ...input.installed ? [] : [`${input.packageManager} install`],
+    runScript(
+      input.packageManager,
+      "flowdular",
+      "setup",
+      "quick",
+      "--apply",
+      "--confirm",
+      "reset-local-auth"
+    ),
+    runScript(input.packageManager, "dev")
+  ];
+}
+function renderNextSteps(input) {
+  return [
+    "",
+    "Next:",
+    "",
+    ...nextSteps(input).map((step) => `  ${step}`),
+    "",
+    `Then open ${DEV_URL} and sign in as admin@example.com.`,
+    ""
+  ].join("\n");
+}
+var HELP = `create-flowdular
+
+Scaffold a Flowdular application: the platform, one example module and the
+secrets a fresh install needs.
+
+Usage
+  npm create flowdular@latest <directory> [options]
+
+Options
+  -t, --template <name>   Template to copy (default: default)
+      --pm <manager>      Use pnpm for the generated workspace (default: pnpm)
+      --no-install        Skip dependency installation
+      --no-git            Skip repository initialization
+  -f, --force             Scaffold into a directory that is not empty
+  -h, --help              Show this help
+  -v, --version           Show the version
+`;
+
+// src/scaffold.ts
+import { readdir as readdir2, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, join as join2, resolve as resolve2 } from "node:path";
+
+// src/secrets.ts
+import { randomBytes } from "node:crypto";
+var SECRET_KEYS = [
+  "FD_AGENT_CREDENTIAL_KEY",
+  "FD_AGENT_RUN_GRANT_KEY",
+  "FD_WORKFLOWS_PAYLOAD_KEY",
+  "FD_WORKFLOWS_CURSOR_KEY",
+  "FD_AUTH_MFA_KEY"
+];
+function generateSecrets() {
+  const secrets = {};
+  for (const key of SECRET_KEYS)
+    secrets[key] = randomBytes(32).toString("base64");
+  return secrets;
+}
+function renderEnvironmentFile(secrets) {
+  return [
+    "# Local configuration for this Flowdular app. Never commit it.",
+    "# Regenerate any key with: openssl rand -base64 32",
+    "",
+    "# Local development runs on embedded PostgreSQL, so there is no server to",
+    "# install and no connection string to configure. A deployment sets",
+    "# FD_DATABASE_ADAPTER=postgresql and the FD_DATABASE_* URLs instead.",
+    "FD_DATABASE_ADAPTER=pglite",
+    "",
+    "# Base64 encoded 32 byte keys, generated once for this app.",
+    ...SECRET_KEYS.map((key) => `${key}=${secrets[key]}`),
+    ""
+  ].join("\n");
+}
+
+// src/template.ts
+import { readdir, copyFile, mkdir } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+function templatesRoot() {
+  return resolve(import.meta.dirname, "..", "template");
+}
+function templateRoot(name) {
+  return join(templatesRoot(), name);
+}
+var RENAMED = { _gitignore: ".gitignore" };
+var TemplateError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TemplateError";
+  }
+};
+function assertInside(root, candidate) {
+  const inside = relative(root, candidate);
+  if (inside.length === 0 || inside === ".." || inside.startsWith(".." + sep)) {
+    throw new TemplateError(
+      `The template tried to write outside the target directory: ${candidate}`
+    );
+  }
+}
+async function copyTemplate(source, destination) {
+  const root = resolve(destination);
+  await mkdir(root, { recursive: true });
+  let files = 0;
+  const pending = [{ from: source, to: root }];
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    const entries = await readdir(directory.from, { withFileTypes: true });
+    for (const entry of entries) {
+      const to = join(directory.to, RENAMED[entry.name] ?? entry.name);
+      assertInside(root, to);
+      const from = join(directory.from, entry.name);
+      if (entry.isDirectory()) {
+        await mkdir(to, { recursive: true });
+        pending.push({ from, to });
+        continue;
+      }
+      if (!entry.isFile()) {
+        throw new TemplateError(
+          `The template contains an entry that is neither a file nor a directory: ${from}`
+        );
+      }
+      await copyFile(from, to);
+      files += 1;
+    }
+  }
+  return files;
+}
+
+// src/scaffold.ts
+var ScaffoldError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ScaffoldError";
+  }
+};
+async function directoryEntries(path) {
+  try {
+    return await readdir2(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+async function assertTemplateExists(path, name) {
+  try {
+    if ((await stat(path)).isDirectory()) return;
+  } catch {
+  }
+  throw new ScaffoldError(`"${name}" is not a template this version ships.`);
+}
+async function rewritePackageName(directory, name) {
+  const path = join2(directory, "package.json");
+  const manifest = JSON.parse(await readFile(path, "utf8"));
+  manifest.name = name;
+  await writeFile(path, JSON.stringify(manifest, void 0, "	") + "\n");
+}
+async function scaffold(request) {
+  const directory = resolve2(request.cwd, request.target);
+  const name = basename(directory);
+  const check = checkProjectName(name);
+  if (!check.valid) {
+    throw new ScaffoldError(
+      `"${name}" is not a valid npm package name: ${check.reason}.`
+    );
+  }
+  const template = templateRoot(request.template);
+  await assertTemplateExists(template, request.template);
+  const existing = await directoryEntries(directory);
+  if (existing.length > 0 && !request.force) {
+    throw new ScaffoldError(
+      `${directory} is not empty. Pass --force to scaffold into it anyway.`
+    );
+  }
+  const files = await copyTemplate(template, directory);
+  await rewritePackageName(directory, name);
+  await writeFile(
+    join2(directory, ".env"),
+    renderEnvironmentFile(request.secrets ?? generateSecrets())
+  );
+  return { directory, name, files: files + 1 };
+}
+
+// src/index.ts
+var processIo = {
+  cwd: process.cwd(),
+  out: (text) => process.stdout.write(text),
+  err: (text) => process.stderr.write(text)
+};
+async function packageVersion() {
+  const manifest = JSON.parse(
+    await readFile2(resolve3(import.meta.dirname, "..", "package.json"), "utf8")
+  );
+  return manifest.version ?? "0.0.0";
+}
+async function run(argv, io = processIo) {
+  let options;
+  try {
+    options = parseArguments(argv);
+  } catch (error) {
+    if (!(error instanceof ArgumentError)) throw error;
+    io.err(`ERROR ${error.message}
+`);
+    return 1;
+  }
+  if (options.help) {
+    io.out(HELP);
+    return 0;
+  }
+  if (options.version) {
+    io.out(`${await packageVersion()}
+`);
+    return 0;
+  }
+  const packageManager = options.packageManager ?? detectPackageManager(process.env.npm_config_user_agent);
+  if (packageManager !== "pnpm") {
+    io.err(
+      "ERROR This template uses pnpm workspaces. Run npm create flowdular@latest my-app without --pm, or choose --pm pnpm.\n"
+    );
+    return 1;
+  }
+  let result;
+  try {
+    result = await scaffold({
+      cwd: io.cwd,
+      target: options.target,
+      template: options.template,
+      force: options.force
+    });
+  } catch (error) {
+    if (!(error instanceof ScaffoldError) && !(error instanceof TemplateError)) {
+      throw error;
+    }
+    io.err(`ERROR ${error.message}
+`);
+    return 1;
+  }
+  io.out(
+    `Created ${result.name} in ${result.directory} (${String(result.files)} files).
+`
+  );
+  let installed = false;
+  if (options.install) {
+    io.out(`Installing dependencies with ${packageManager}.
+`);
+    const install = installDependencies(packageManager, result.directory);
+    installed = install.ok;
+    if (!install.ok) io.err(`WARNING ${install.reason}.
+`);
+  }
+  if (options.git) {
+    const git2 = initializeRepository(result.directory);
+    if (!git2.ok) io.err(`WARNING ${git2.reason}.
+`);
+  }
+  const here = relative2(io.cwd, result.directory);
+  io.out(
+    renderNextSteps({
+      directory: here.length > 0 ? here : ".",
+      packageManager,
+      installed
+    })
+  );
+  return 0;
+}
+
+// src/bin.ts
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "create-flowdular",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Scaffold a Flowdular application: the platform, one example module and the secrets a fresh install needs.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/flowdular/flowdular.git",
+		"directory": "packages/create-flowdular"
+	},
+	"homepage": "https://flowdular.com",
+	"bugs": "https://github.com/flowdular/flowdular/issues",
+	"keywords": [
+		"flowdular",
+		"octanejs",
+		"scaffold",
+		"create",
+		"starter"
+	],
+	"bin": {
+		"create-flowdular": "./dist/bin.js"
+	},
+	"files": [
+		"dist",
+		"template",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=22.22.2"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/template/default/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+	"plugins": ["@tsrx/prettier-plugin"],
+	"singleQuote": true,
+	"trailingComma": "all",
+	"useTabs": true
+}

package/template/default/README.md

@@ -0,0 +1,56 @@
+# Flowdular app
+
+Created with `npx create-flowdular@latest`. This is the Flowdular platform, one
+example module, and nothing else you have to configure.
+
+## Run it
+
+```bash
+pnpm install
+pnpm flowdular setup quick --apply --confirm reset-local-auth
+pnpm dev
+```
+
+Open <http://localhost:4310> and sign in as `admin@example.com`. Quick setup is
+a destructive local reset: stop `pnpm dev` first, and never point it at a
+deployed database.
+
+Local development runs on embedded PostgreSQL, so there is no database server to
+install. Data lives under `.flowdular/data`.
+
+## What is here
+
+| Path              | Contents                                                     |
+| ----------------- | ------------------------------------------------------------ |
+| `platform`        | The deployable composition root and the application shell    |
+| `modules/example` | A tenant-scoped record module: API, migration, screen, tests |
+| `flowdular.json`  | Enabled modules and locales, owned by the CLI                |
+| `.env`            | The keys generated for this app. Never commit it             |
+
+## Build your first module
+
+```bash
+pnpm flowdular module new sales.orders --spec modules/sales-orders/spec/module.yaml
+pnpm flowdular module new sales.orders --spec modules/sales-orders/spec/module.yaml --apply
+pnpm flowdular module enable sales.orders --apply
+```
+
+A module is created only from a spec with `status: approved`. Copy
+`modules/example` for the shape: an approved spec, one permission per action,
+tenant-scoped SQL with forced row-level security, translations per locale, and
+tests.
+
+`platform/src/generated/**`, `platform/package.json` dependencies and
+`modules.enabled` in `flowdular.json` are written by the CLI. Never edit them by
+hand.
+
+## Commands
+
+```bash
+pnpm dev              # platform with HMR on http://localhost:4310
+pnpm verify           # typecheck, tests, module validation, format
+pnpm flowdular doctor  # workspace health
+```
+
+Every write command is a dry run without `--apply`; destructive ones also need
+`--confirm`.

package/template/default/_gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.flowdular/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store