@tyndall/create-app 0.0.1

package/README.md

@@ -0,0 +1,24 @@
+# @tyndall/create-app
+
+## Overview
+Scaffolding package for creating new Hyper applications with a React baseline.
+
+## Responsibilities
+- Validate scaffold arguments and target directory safety.
+- Generate deterministic starter files (`package.json`, `hyper.config.ts`, `tsconfig.json`, `biome.json`, pages, public assets).
+- Configure generated apps to use `cloud-front lint` / `cloud-front format`.
+- Apply an initial Biome format + lint baseline through `@tyndall/lint` when CLI scaffolding runs.
+
+## Public API Highlights
+- `createCloudApp(targetDir, options)`
+- `CreateCloudAppOptions.lintFormat.enabled` for optional post-scaffold quality application in programmatic usage.
+- CLI: `@tyndall/create-app <dir> [--ui react] [--no-lint-format]`
+
+## Development
+- Build: `bun run --filter @tyndall/create-app build`
+- Test (from workspace root): `bun test`
+
+## Documentation
+- Package specification: [spec.md](./spec.md)
+- Package architecture: [architecture.md](./architecture.md)
+- Package changes: [CHANGELOG.md](./CHANGELOG.md)

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { type FormatOptions, type LintOptions } from "@tyndall/lint";
+declare const SUPPORTED_UI: readonly ["react"];
+export type UiLibrary = (typeof SUPPORTED_UI)[number];
+interface LintToolResult {
+    code: number;
+    error?: Error;
+}
+export interface ScaffoldLintFormatOptions {
+    enabled?: boolean;
+    runLint?: (options: LintOptions) => Promise<LintToolResult>;
+    runFormat?: (options: FormatOptions) => Promise<LintToolResult>;
+}
+export interface CreateCloudAppOptions {
+    ui?: UiLibrary;
+    lintFormat?: ScaffoldLintFormatOptions;
+}
+export interface CreateCloudAppResult {
+    rootDir: string;
+    ui: UiLibrary;
+    files: string[];
+    lintFormatApplied: boolean;
+}
+export declare const createCloudApp: (targetDir: string, options?: CreateCloudAppOptions) => Promise<CreateCloudAppResult>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAIA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,QAAA,MAAM,YAAY,oBAAqB,CAAC;AACxC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,UAAU,CAAC,EAAE,yBAAyB,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAwLD,eAAO,MAAM,cAAc,GACzB,WAAW,MAAM,EACjB,UAAS,qBAA0B,KAClC,OAAO,CAAC,oBAAoB,CAmB9B,CAAC"}

package/dist/index.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runFormat as defaultRunFormat, runLint as defaultRunLint, } from "@tyndall/lint";
+const SUPPORTED_UI = ["react"];
+const USAGE = `@tyndall/create-app <dir> [--ui react]
+
+Options:
+  --ui <library>   UI adapter to scaffold (react only)
+  --no-lint-format Skip automatic Biome format/lint baseline
+  -h, --help       Show this help message
+`;
+const normalizeUi = (ui) => {
+    const normalized = (ui ?? "react").toLowerCase();
+    // Keep UI selection strict to avoid generating incompatible scaffolds.
+    if (!SUPPORTED_UI.includes(normalized)) {
+        throw new Error(`Unsupported ui library: ${ui}. Supported: ${SUPPORTED_UI.join(", ")}`);
+    }
+    return normalized;
+};
+const ensureEmptyDir = async (rootDir) => {
+    let info = null;
+    try {
+        info = await stat(rootDir);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            await mkdir(rootDir, { recursive: true });
+            return;
+        }
+        throw error;
+    }
+    if (!info.isDirectory()) {
+        throw new Error("Target path exists and is not a directory.");
+    }
+    const entries = await readdir(rootDir);
+    // Protect against clobbering an existing project directory.
+    if (entries.length > 0) {
+        throw new Error("Target directory must be empty.");
+    }
+};
+const toPackageName = (rawName) => {
+    const cleaned = rawName
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "");
+    return cleaned.length > 0 ? cleaned : "hyper-app";
+};
+const buildTemplateFiles = (appName, ui) => {
+    const packageName = toPackageName(appName);
+    const files = {
+        "package.json": JSON.stringify({
+            name: packageName,
+            private: true,
+            type: "module",
+            scripts: {
+                dev: "cloud-front dev",
+                build: "cloud-front build",
+                start: "cloud-front start",
+                lint: "cloud-front lint",
+                format: "cloud-front format",
+            },
+            dependencies: {
+                react: "^18.2.0",
+                "react-dom": "^18.2.0",
+                "@tyndall/react": "workspace:*",
+            },
+            devDependencies: {
+                "@tyndall/cli": "workspace:*",
+                "@tyndall/lint": "workspace:*",
+            },
+        }, null, 2),
+        "biome.json": JSON.stringify({
+            $schema: "https://biomejs.dev/schemas/latest/schema.json",
+            formatter: {
+                enabled: true,
+                indentStyle: "space",
+                indentWidth: 2,
+                lineWidth: 100,
+            },
+            linter: {
+                enabled: true,
+                rules: {
+                    recommended: true,
+                },
+            },
+            javascript: {
+                formatter: {
+                    quoteStyle: "double",
+                    semicolons: "always",
+                    trailingCommas: "all",
+                },
+            },
+        }, null, 2) + "\n",
+        "hyper.config.ts": ui === "react"
+            ? [
+                "import { createReactUiAdapterFactory } from \"@tyndall/react\";",
+                "",
+                "export default {",
+                "  ui: {",
+                "    adapter: createReactUiAdapterFactory(),",
+                "  },",
+                "};",
+                "",
+            ].join("\n")
+            : `export default {\n  ui: { adapter: \"${ui}\" },\n};\n`,
+        "tsconfig.json": JSON.stringify({
+            compilerOptions: {
+                target: "ES2020",
+                module: "ESNext",
+                moduleResolution: "Bundler",
+                jsx: "react-jsx",
+                strict: true,
+            },
+            include: ["src"],
+        }, null, 2),
+        "README.md": `# ${appName}\n\nThis app was scaffolded with @tyndall/create-app.\n\n## Commands\n- \`bun run dev\`\n- \`bun run build\`\n- \`bun run start\`\n- \`bun run lint\`\n- \`bun run format\`\n`,
+        ".gitignore": "node_modules\ndist\n.hyper\n",
+        "public/robots.txt": "User-agent: *\nAllow: /\n",
+        "src/pages/index.tsx": `export default function Home() {\n  return (\n    <main>\n      <h1>Hyper App</h1>\n      <p>Welcome to your new Hyper project.</p>\n    </main>\n  );\n}\n`,
+    };
+    return files;
+};
+const writeFiles = async (rootDir, files) => {
+    const written = [];
+    for (const [relativePath, contents] of Object.entries(files)) {
+        const filePath = join(rootDir, relativePath);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, contents, "utf-8");
+        written.push(relativePath);
+    }
+    return written;
+};
+const runLintFormatStep = async (mode, operation) => {
+    const result = await operation();
+    if (result.code === 0) {
+        return;
+    }
+    const errorDetail = result.error?.message ? ` ${result.error.message}` : "";
+    throw new Error(`Failed to apply ${mode} baseline (exit code: ${result.code}).${errorDetail}`);
+};
+const applyLintFormatBaseline = async (rootDir, options) => {
+    const runFormat = options.runFormat ?? defaultRunFormat;
+    const runLint = options.runLint ?? defaultRunLint;
+    await runLintFormatStep("format", () => runFormat({
+        cwd: rootDir,
+        write: true,
+        files: ["."],
+    }));
+    await runLintFormatStep("lint", () => runLint({
+        cwd: rootDir,
+        fix: true,
+        files: ["."],
+    }));
+};
+export const createCloudApp = async (targetDir, options = {}) => {
+    if (!targetDir || targetDir.trim().length === 0) {
+        throw new Error("Target directory is required.");
+    }
+    const ui = normalizeUi(options.ui);
+    const rootDir = resolve(process.cwd(), targetDir);
+    await ensureEmptyDir(rootDir);
+    const appName = basename(rootDir);
+    const files = buildTemplateFiles(appName, ui);
+    const written = await writeFiles(rootDir, files);
+    const lintFormat = options.lintFormat ?? {};
+    const lintFormatApplied = lintFormat.enabled ?? false;
+    if (lintFormatApplied) {
+        await applyLintFormatBaseline(rootDir, lintFormat);
+    }
+    return { rootDir, ui, files: written, lintFormatApplied };
+};
+const parseCliArgs = (argv) => {
+    const args = [...argv];
+    let targetDir = "";
+    let ui;
+    let showHelp = false;
+    let applyLintFormat = true;
+    while (args.length > 0) {
+        const next = args.shift();
+        if (!next) {
+            break;
+        }
+        if (next === "-h" || next === "--help") {
+            showHelp = true;
+            continue;
+        }
+        if (next === "--ui") {
+            const value = args.shift();
+            if (!value) {
+                throw new Error("--ui requires a value.");
+            }
+            ui = normalizeUi(value);
+            continue;
+        }
+        if (next === "--no-lint-format") {
+            applyLintFormat = false;
+            continue;
+        }
+        if (next.startsWith("--ui=")) {
+            const value = next.split("=").slice(1).join("=");
+            ui = normalizeUi(value);
+            continue;
+        }
+        if (next.startsWith("--")) {
+            throw new Error(`Unknown option: ${next}`);
+        }
+        if (!targetDir) {
+            targetDir = next;
+            continue;
+        }
+        throw new Error(`Unexpected argument: ${next}`);
+    }
+    return { targetDir, ui, showHelp, applyLintFormat };
+};
+const isMain = () => {
+    if (!process.argv[1]) {
+        return false;
+    }
+    return resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+};
+if (isMain()) {
+    try {
+        const { targetDir, ui, showHelp, applyLintFormat } = parseCliArgs(process.argv.slice(2));
+        if (showHelp || !targetDir) {
+            const exitCode = showHelp ? 0 : 1;
+            if (!showHelp) {
+                console.error("Target directory is required.");
+            }
+            console.log(USAGE);
+            process.exit(exitCode);
+        }
+        const result = await createCloudApp(targetDir, {
+            ui,
+            lintFormat: { enabled: applyLintFormat },
+        });
+        console.log(`Created Hyper app at ${result.rootDir} (ui: ${result.ui}).`);
+        if (result.lintFormatApplied) {
+            console.log("Applied Biome lint/format baseline via @tyndall/lint.");
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`@tyndall/create-app failed: ${message}`);
+        process.exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@tyndall/create-app",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "create-cloud-app": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@tyndall/lint": "workspace:*"
+  }
+}