create-syncular-app 0.1.3 → 0.2.1

package/README.md

@@ -1,39 +1,82 @@
 # create-syncular-app
 
-Scaffold a local-first [Syncular](https://syncular.dev) app in one command:
+The `create-syncular-app` scaffolder — the create-app experience for syncular v2.
 
-```bash
-bunx create-syncular-app my-app
-# or
-npm create syncular-app@latest my-app
-pnpm create syncular-app my-app
+```sh
+bun create syncular-app my-app            # prompts for the template
+bunx create-syncular-app my-app --template web
 ```
 
-Then:
+> Naming (`@syncular/*`, bin `create-syncular-app`, CLI `syncular`) is not
+> final — package identity is TODO 6.3. Every user-visible name lives in
+> [`src/constants.ts`](./src/constants.ts) so a rename is mechanical: edit the
+> constants, regenerate the templates' generated files, done.
 
-```bash
-cd my-app
-bun install
-bun dev
-```
+## Templates
+
+| Template | Shape |
+|---|---|
+| `minimal` | Server + a terminal two-client convergence demo (no browser) — migrations + manifest + `generate` wiring. Copy-evolved from `examples/quickstart`. The smallest honest starting point. |
+| `web` | Hono server + WebSocket realtime + a single-pane browser todo app whose whole client core runs in a Web Worker on OPFS. Derived from `apps/demo`, slimmed to one pane (no conflict simulator, no blob attachments) — the minimal browser app a real user starts from. |
+
+> **Third-template candidate: `react`.** [`apps/demo-react`](../../apps/demo-react)
+> is the ready-made source for a hooks-based template — `@syncular/react`
+> (`SyncProvider` + `useTypedQuery` + `useMutation` + `useSyncStatus` +
+> `useWindow`) over the same worker + OPFS core, with the Kysely-typed read
+> layer wired. Slim it the way `web` slims `apps/demo` (drop the three-list
+> seed to one, keep one hook of each kind) and add it here when a React
+> template is wanted. Not built yet — noted so the shape is on record.
+
+Each template ships its own `README.md` (run steps, what to edit first),
+`.gitignore` (as `gitignore` — see below), a working `tsconfig.json`, and a
+smoke test.
+
+## The local-vs-published dependency mechanism
+
+Template `package.json` files use `workspace:*` ranges for every
+`@syncular/*` dependency. At scaffold time the scaffolder rewrites those
+ranges:
+
+- **`--local`** (or the in-tree test path): keep `workspace:*` verbatim. These
+  are the only ranges that resolve when the scaffolded app sits inside this
+  repo's workspace.
+- **default** (a normal `bunx create-…` run): rewrite to
+  `PUBLISHED_DEPENDENCY_RANGE` (`src/constants.ts`). **Today that constant is
+  *also* `workspace:*`** because the v2 packages are unpublished and
+  version-less (all `private`, no `version` — TODO 6.3), so there is no honest
+  semver range yet. The CLI **warns loudly** in this case: a `bun install`
+  outside the repo cannot resolve the deps until publishing lands. When the
+  packages ship, flip that one constant to `^<version>` (or teach the CLI to
+  read the published version) — a single edit.
+
+`.gitignore` ships as `gitignore` (no dot) because npm strips real dotfiles
+from published tarballs; the scaffolder renames it on copy.
 
-You get a minimal, working local-first todo app:
+Placeholder substitution is deliberately dumb and greppable: the only token is
+`__PROJECT_NAME__` (in each template's `package.json` and `README.md`),
+replaced with the derived package name.
 
-- SQL schema in `migrations/`, mapped to subscriptions/scopes in
-  `syncular.app.ts`
-- a committed, pre-generated TypeScript client (`src/generated/`) — no extra
-  toolchain needed to run; regenerate with `npx syncular generate`
-- a Hono sync server on Bun + SQLite (`src/server/sync-server.ts`)
-- a React UI on `@syncular/client/react` with live queries and offline-queued
-  mutations (`src/app.tsx`)
+## How the templates are tested (and how the tier splits)
 
-The scaffolded README explains the project layout and how to evolve the
-schema.
+`test/scaffold.test.ts` exercises the TEMPLATES THEMSELVES, not just the
+scaffolder logic. For each template it:
 
-## Links
+1. scaffolds into a temp dir (`--local`),
+2. asserts the tree shape + placeholder substitution + package.json rewrite,
+3. runs `syncular generate --check` — proving the committed
+   `syncular.generated.ts` is byte-fresh,
+4. links a `node_modules` into the temp dir **offline** (see
+   [`test/link-workspace.ts`](./test/link-workspace.ts): `@syncular/*` →
+   the real package dirs, external deps → the workspace `.bun` hoist store),
+   typechecks the template's own files, and runs the app's own `bun test`
+   smoke.
 
-- Documentation: https://syncular.dev/docs
-- GitHub: https://github.com/syncular/syncular
-- Issues: https://github.com/syncular/syncular/issues
+Steps 1–4 are the **always-run tier** — offline and fast (~1.5s total), so
+they ride the normal `bun run check`. A **full-fidelity tier** behind
+`SYNCULAR_TEMPLATE_INSTALL=1` additionally does a real `bun install` per
+template before running the smoke; it is opt-in because it needs the network.
 
-> Status: Alpha. APIs and storage layouts may change between releases.
+The in-tree template `*.test.ts` files are excluded from the root `bun test`
+sweep (`--path-ignore-patterns '**/create-app/template/**'` in the root `test`
+script) — they can only resolve their deps inside a scaffolded, linked copy,
+which the tier test above provides.

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { type TemplateName } from './scaffold.js';
+interface ParsedArgs {
+    readonly help: boolean;
+    readonly local: boolean;
+    readonly projectName?: string;
+    readonly template?: TemplateName;
+}
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export declare function runCli(argv?: string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -1,197 +1,149 @@
 #!/usr/bin/env node
-
-// src/cli.ts
-import {
-  cpSync,
-  existsSync,
-  readdirSync,
-  readFileSync,
-  renameSync,
-  writeFileSync
-} from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { createInterface } from "node:readline/promises";
-import { fileURLToPath, pathToFileURL } from "node:url";
-var FALLBACK_SYNCULAR_VERSION_RANGE = "^0.1.3";
+/**
+ * `create-syncular-app [project-name] [--template <minimal|web>] [--local]`
+ *
+ * Runnable as `bun create syncular-app my-app` or `bunx create-syncular-app
+ * my-app`. Prompts for anything a flag did not supply. Scaffolds one of the
+ * two templates (see `./scaffold`).
+ */
+import { relative } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { CLI_BIN, CREATE_BIN, PRODUCT_NAME } from './constants.js';
+import { isTemplateName, scaffoldApp, TEMPLATES, } from './scaffold.js';
 function usage() {
-  return `usage: create-syncular-app <target-dir>
+    return `usage: ${CREATE_BIN} [project-name] [options]
+
+Scaffolds a ${PRODUCT_NAME} v2 starter app.
+
+templates:
+  minimal   server + a terminal two-client convergence demo (no browser)
+  web       Hono server + WebSocket + a single-pane browser todo app
+            (worker core on OPFS)
 
-Scaffolds a local-first Syncular starter app (tasks table, Hono sync server,
-React client) into <target-dir>.
+options:
+  --template <name>   one of: ${TEMPLATES.join(', ')} (prompts if omitted)
+  --local             keep workspace:* deps (scaffolding inside this repo)
+  -h, --help          show this help
 
 examples:
-  bunx create-syncular-app my-app
-  npm create syncular-app@latest my-app
-  pnpm create syncular-app my-app
+  bun create syncular-app my-app
+  bunx ${CREATE_BIN} my-app --template web
 `;
 }
-function parseCreateCliArgs(argv) {
-  const options = { help: false };
-  for (const arg of argv) {
-    if (arg === "--help" || arg === "-h") {
-      options.help = true;
-      continue;
+export function parseArgs(argv) {
+    let help = false;
+    let local = false;
+    let projectName;
+    let template;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            help = true;
+        }
+        else if (arg === '--local') {
+            local = true;
+        }
+        else if (arg === '--template') {
+            const value = argv[i + 1];
+            if (value === undefined)
+                throw new Error('--template requires a value');
+            if (!isTemplateName(value)) {
+                throw new Error(`unknown template ${JSON.stringify(value)} (expected: ${TEMPLATES.join(', ')})`);
+            }
+            template = value;
+            i += 1;
+        }
+        else if (arg?.startsWith('-')) {
+            throw new Error(`unknown option ${JSON.stringify(arg)}\n\n${usage()}`);
+        }
+        else if (projectName === undefined) {
+            projectName = arg;
+        }
+        else {
+            throw new Error(`unexpected extra argument ${JSON.stringify(arg)}`);
+        }
     }
-    if (arg.startsWith("-")) {
-      throw new Error(`Unknown option: ${arg}
-
-${usage()}`);
+    return {
+        help,
+        local,
+        ...(projectName !== undefined ? { projectName } : {}),
+        ...(template !== undefined ? { template } : {}),
+    };
+}
+async function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim();
     }
-    if (options.targetDir !== undefined) {
-      throw new Error(`Unexpected extra argument: ${arg}
-
-${usage()}`);
+    finally {
+        rl.close();
     }
-    options.targetDir = arg;
-  }
-  return options;
-}
-function packageNameFromDirectory(targetDir) {
-  const name = basename(resolve(targetDir)).toLowerCase().replace(/[^a-z0-9-_.~]+/g, "-").replace(/^[-._]+|[-._]+$/g, "");
-  return name.length > 0 ? name : "syncular-app";
 }
-function syncularDependencyRange(ownVersion) {
-  const version = ownVersion?.trim();
-  if (!version || version === "0.0.0") {
-    return FALLBACK_SYNCULAR_VERSION_RANGE;
-  }
-  return `^${version}`;
-}
-function isSyncularPackage(dependencyName) {
-  return dependencyName === "syncular" || dependencyName.startsWith("@syncular/");
-}
-function rewriteTemplatePackageJson(source, options) {
-  const pkg = JSON.parse(source);
-  pkg.name = options.packageName;
-  for (const section of [pkg.dependencies, pkg.devDependencies]) {
-    if (!section)
-      continue;
-    for (const [name, range] of Object.entries(section)) {
-      if (isSyncularPackage(name) && range.startsWith("workspace:")) {
-        section[name] = options.syncularRange;
-      }
+async function resolveTemplate(supplied) {
+    if (supplied !== undefined)
+        return supplied;
+    const answer = await prompt(`Template? (${TEMPLATES.join(' / ')}) [minimal]: `);
+    if (answer === '')
+        return 'minimal';
+    if (!isTemplateName(answer)) {
+        throw new Error(`unknown template ${JSON.stringify(answer)} (expected: ${TEMPLATES.join(', ')})`);
     }
-  }
-  return `${JSON.stringify(pkg, null, 2)}
-`;
-}
-function detectPackageManager(userAgent = process.env.npm_config_user_agent) {
-  if (!userAgent)
-    return "bun";
-  if (userAgent.startsWith("bun"))
-    return "bun";
-  if (userAgent.startsWith("pnpm"))
-    return "pnpm";
-  if (userAgent.startsWith("yarn"))
-    return "yarn";
-  if (userAgent.startsWith("npm"))
-    return "npm";
-  return "bun";
-}
-function nextStepsMessage(targetDir, packageManager) {
-  const install = packageManager === "yarn" ? "yarn" : `${packageManager} install`;
-  const dev = packageManager === "bun" ? "bun dev" : `${packageManager} run dev`;
-  return `
-Done. Next steps:
-
-  cd ${targetDir}
-  ${install}
-  ${dev}
-
-The dev script starts the sync server (http://127.0.0.1:4100/health) and the
-Vite client (http://127.0.0.1:5173). The app itself runs on Bun (the sync
-server uses Bun.serve + bun:sqlite); install it from https://bun.sh if needed.
-
-Read the generated README.md for the project layout and how to evolve the
-schema.
-`;
-}
-function readOwnVersion() {
-  try {
-    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    return packageJson.version;
-  } catch {
-    return;
-  }
-}
-function templateDirectory() {
-  return fileURLToPath(new URL("../template", import.meta.url));
-}
-function directoryIsEmpty(path) {
-  return readdirSync(path).length === 0;
-}
-async function promptTargetDir() {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = await rl.question("Target directory (e.g. my-app): ");
-    return answer.trim();
-  } finally {
-    rl.close();
-  }
-}
-function scaffoldApp(targetDirInput) {
-  const targetDir = resolve(targetDirInput);
-  const templateDir = templateDirectory();
-  if (!existsSync(templateDir)) {
-    throw new Error(`Bundled template not found at ${templateDir}`);
-  }
-  if (existsSync(targetDir) && !directoryIsEmpty(targetDir)) {
-    throw new Error(`Target directory is not empty: ${targetDir}`);
-  }
-  cpSync(templateDir, targetDir, { recursive: true });
-  const gitignorePlaceholder = join(targetDir, "_gitignore");
-  if (existsSync(gitignorePlaceholder)) {
-    renameSync(gitignorePlaceholder, join(targetDir, ".gitignore"));
-  }
-  const packageName = packageNameFromDirectory(targetDir);
-  const syncularRange = syncularDependencyRange(readOwnVersion());
-  const packageJsonPath = join(targetDir, "package.json");
-  writeFileSync(packageJsonPath, rewriteTemplatePackageJson(readFileSync(packageJsonPath, "utf8"), {
-    packageName,
-    syncularRange
-  }));
-  return { targetDir, packageName, syncularRange };
-}
-async function runCreateSyncularAppCli(argv = process.argv.slice(2)) {
-  try {
-    const options = parseCreateCliArgs(argv);
-    if (options.help) {
-      console.log(usage());
-      return 0;
+    return answer;
+}
+function nextSteps(dir, template) {
+    const cd = `  cd ${dir}\n  bun install`;
+    const run = template === 'web'
+        ? '  bun run dev          # http://localhost:8787'
+        : '  bun run server       # terminal 1\n  bun run clients      # terminal 2 — prints "✓ converged"';
+    return `\nDone. Next steps:\n\n${cd}\n  bun run generate     # migrations → src/syncular.generated.ts\n${run}\n\nSee README.md for the layout and what to edit first.\n`;
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        console.error(`[${CREATE_BIN}] ${describe(error)}`);
+        return 1;
+    }
+    if (args.help) {
+        console.log(usage());
+        return 0;
     }
-    let targetDirInput = options.targetDir;
-    if (!targetDirInput) {
-      targetDirInput = await promptTargetDir();
+    try {
+        let projectName = args.projectName;
+        if (projectName === undefined || projectName === '') {
+            projectName = await prompt('Project directory (e.g. my-app): ');
+        }
+        if (projectName === '') {
+            console.error(`[${CREATE_BIN}] a project directory is required`);
+            return 1;
+        }
+        const template = await resolveTemplate(args.template);
+        const result = scaffoldApp({
+            template,
+            targetDir: projectName,
+            local: args.local,
+        });
+        const displayDir = relative(process.cwd(), result.targetDir) || '.';
+        console.log(`[${CREATE_BIN}] scaffolded ${result.packageName} (template: ${template}) into ${displayDir}`);
+        if (!result.local) {
+            console.warn(`[${CREATE_BIN}] note: the ${PRODUCT_NAME} v2 packages are not published yet, so\n` +
+                `  the app's dependencies are still workspace:* ranges. Run inside this repo\n` +
+                `  (or pass --local) until publishing lands (TODO 6.3). Use \`${CLI_BIN} generate\`\n` +
+                '  to (re)generate the typed schema.');
+        }
+        console.log(nextSteps(displayDir, template));
+        return 0;
     }
-    if (!targetDirInput) {
-      console.error("[create-syncular-app] A target directory is required.");
-      console.error(usage());
-      return 1;
+    catch (error) {
+        console.error(`[${CREATE_BIN}] ${describe(error)}`);
+        return 1;
     }
-    const result = scaffoldApp(targetDirInput);
-    console.log(`[create-syncular-app] Scaffolded ${result.packageName} into ${result.targetDir} (Syncular packages at ${result.syncularRange}).`);
-    console.log(nextStepsMessage(targetDirInput, detectPackageManager()));
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`[create-syncular-app] ${message}`);
-    return 1;
-  }
 }
-function isMainModule() {
-  const entrypoint = process.argv[1];
-  return entrypoint !== undefined && import.meta.url === pathToFileURL(entrypoint).href;
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-if (isMainModule()) {
-  process.exitCode = await runCreateSyncularAppCli();
+if (import.meta.main) {
+    process.exitCode = await runCli();
 }
-export {
-  syncularDependencyRange,
-  scaffoldApp,
-  runCreateSyncularAppCli,
-  rewriteTemplatePackageJson,
-  parseCreateCliArgs,
-  packageNameFromDirectory,
-  nextStepsMessage,
-  detectPackageManager
-};

package/dist/constants.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The ONE place naming lives (TODO 6.3 is a product decision — final package
+ * identity is not settled). Every user-visible name the scaffolder emits comes
+ * from here so a rename is mechanical: change these constants, regenerate the
+ * templates' generated files, done. No name is hardcoded elsewhere in this
+ * package — grep for the literals below and you should only find them here.
+ */
+/** The scoped npm namespace for the v2 packages, e.g. `@syncular`. */
+export declare const PACKAGE_SCOPE = "@syncular";
+/** The typegen CLI binary name (`syncular generate`, `syncular init`). */
+export declare const CLI_BIN = "syncular";
+/** This package's own bin (`bun create syncular …` / `bunx create-syncular-app …`). */
+export declare const CREATE_BIN = "create-syncular-app";
+/** Human-facing product name in prose. */
+export declare const PRODUCT_NAME = "syncular";
+/**
+ * The scoped workspace packages a template may depend on. The scaffolder only
+ * rewrites ranges for packages under {@link PACKAGE_SCOPE}, so this list is
+ * documentation, not a gate — but it keeps the "what does a template pull in"
+ * question answerable from one spot.
+ */
+export declare const WORKSPACE_PACKAGES: readonly ["@syncular/core", "@syncular/server", "@syncular/server-hono", "@syncular/client", "@syncular/typegen"];
+/**
+ * The dependency range written into a scaffolded app's package.json when NOT
+ * scaffolding for in-tree testing (see {@link scaffoldApp}'s `local` flag).
+ *
+ * The v2 packages are unpublished and version-less today (all `private`, no
+ * `version` field — final identity + the release train is TODO 6.3). Until
+ * they publish there is no honest semver range to point at, so this is a
+ * `workspace:*`-shaped LOCAL default too, and the CLI warns loudly that a
+ * published install is not yet possible. When the packages ship, replace this
+ * with `^<version>` (or teach the CLI to read the published version) — one
+ * edit, here.
+ */
+export declare const PUBLISHED_DEPENDENCY_RANGE = "workspace:*";
+/** Placeholder tokens substituted verbatim during scaffold (dumb + greppable). */
+export declare const PLACEHOLDER: {
+    /** Replaced by the chosen project name in package.json/README. */
+    readonly projectName: "__PROJECT_NAME__";
+};

package/dist/constants.js

@@ -0,0 +1,46 @@
+/**
+ * The ONE place naming lives (TODO 6.3 is a product decision — final package
+ * identity is not settled). Every user-visible name the scaffolder emits comes
+ * from here so a rename is mechanical: change these constants, regenerate the
+ * templates' generated files, done. No name is hardcoded elsewhere in this
+ * package — grep for the literals below and you should only find them here.
+ */
+/** The scoped npm namespace for the v2 packages, e.g. `@syncular`. */
+export const PACKAGE_SCOPE = '@syncular';
+/** The typegen CLI binary name (`syncular generate`, `syncular init`). */
+export const CLI_BIN = 'syncular';
+/** This package's own bin (`bun create syncular …` / `bunx create-syncular-app …`). */
+export const CREATE_BIN = 'create-syncular-app';
+/** Human-facing product name in prose. */
+export const PRODUCT_NAME = 'syncular';
+/**
+ * The scoped workspace packages a template may depend on. The scaffolder only
+ * rewrites ranges for packages under {@link PACKAGE_SCOPE}, so this list is
+ * documentation, not a gate — but it keeps the "what does a template pull in"
+ * question answerable from one spot.
+ */
+export const WORKSPACE_PACKAGES = [
+    `${PACKAGE_SCOPE}/core`,
+    `${PACKAGE_SCOPE}/server`,
+    `${PACKAGE_SCOPE}/server-hono`,
+    `${PACKAGE_SCOPE}/client`,
+    `${PACKAGE_SCOPE}/typegen`,
+];
+/**
+ * The dependency range written into a scaffolded app's package.json when NOT
+ * scaffolding for in-tree testing (see {@link scaffoldApp}'s `local` flag).
+ *
+ * The v2 packages are unpublished and version-less today (all `private`, no
+ * `version` field — final identity + the release train is TODO 6.3). Until
+ * they publish there is no honest semver range to point at, so this is a
+ * `workspace:*`-shaped LOCAL default too, and the CLI warns loudly that a
+ * published install is not yet possible. When the packages ship, replace this
+ * with `^<version>` (or teach the CLI to read the published version) — one
+ * edit, here.
+ */
+export const PUBLISHED_DEPENDENCY_RANGE = 'workspace:*';
+/** Placeholder tokens substituted verbatim during scaffold (dumb + greppable). */
+export const PLACEHOLDER = {
+    /** Replaced by the chosen project name in package.json/README. */
+    projectName: '__PROJECT_NAME__',
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** Programmatic surface (the CLI is the primary entry; tests use these). */
+export * from './constants.js';
+export * from './scaffold.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+/** Programmatic surface (the CLI is the primary entry; tests use these). */
+export * from './constants.js';
+export * from './scaffold.js';

package/dist/scaffold.d.ts

@@ -0,0 +1,44 @@
+/** The two templates this rung ships. */
+export declare const TEMPLATES: readonly ["minimal", "web"];
+export type TemplateName = (typeof TEMPLATES)[number];
+export declare function isTemplateName(value: string): value is TemplateName;
+/** Absolute path to `template/` inside this package (works for src or dist). */
+export declare function templatesRoot(): string;
+/** Derive a safe npm package name from the target directory basename. */
+export declare function packageNameFromDirectory(targetDir: string): string;
+/**
+ * Rewrite a template's package.json: set `name`, and resolve the dependency
+ * range for every `@<scope>/*` workspace dependency.
+ *
+ * The local-vs-published question, decided honestly (also documented in the
+ * package README):
+ * - `local: true` keeps `workspace:*` verbatim — the only ranges that resolve
+ *   when the scaffolded app sits inside this repo's workspace (the in-tree
+ *   smoke test path, and `--local` for anyone hacking on the tree).
+ * - `local: false` rewrites to {@link PUBLISHED_DEPENDENCY_RANGE}. Today that
+ *   is *also* `workspace:*` because the v2 packages are unpublished and
+ *   version-less (TODO 6.3); the CLI warns. It is one constant to flip the day
+ *   they publish.
+ */
+export declare function rewriteTemplatePackageJson(source: string, options: {
+    packageName: string;
+    local: boolean;
+}): string;
+export interface ScaffoldOptions {
+    readonly template: TemplateName;
+    readonly targetDir: string;
+    /** Keep `workspace:*` ranges (in-tree testing / repo hacking). */
+    readonly local?: boolean;
+}
+export interface ScaffoldResult {
+    readonly targetDir: string;
+    readonly packageName: string;
+    readonly template: TemplateName;
+    readonly local: boolean;
+}
+/**
+ * Copy `template/<template>` into `targetDir` and finalize it: restore the
+ * `.gitignore` name (npm strips real dotfiles from tarballs, so templates ship
+ * `gitignore`), rewrite package.json, and substitute placeholders.
+ */
+export declare function scaffoldApp(options: ScaffoldOptions): ScaffoldResult;