march-hare 0.13.0 → 0.13.2

package/dist/cli/lib/commands/feature/index.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import kleur from "kleur";
+import { pascalCase } from "change-case";
+import { scaffold } from "../../runner/index.js";
+import { askName, askConfirm, pickDirectory, requireProjectRoot, } from "../../prompt/index.js";
+async function resolveStateful(flags) {
+    if (flags.stateful !== undefined)
+        return flags.stateful !== false;
+    if (flags.presentational !== undefined)
+        return flags.presentational === false;
+    return askConfirm("Does this feature own state and actions?", true);
+}
+export async function newFeature({ positional, flags, }) {
+    const root = requireProjectRoot();
+    const name = positional[0] || (await askName("Feature name (kebab-case)"));
+    const stateful = await resolveStateful(flags);
+    const action = stateful ? "stateful" : "presentational";
+    await scaffold("feature", action, { name, pascalName: pascalCase(name) }, { cwd: root });
+    console.log(kleur.green("\n  Feature ready."), kleur.dim(`Mount it inside a page with <${pascalCase(name)} />.`));
+}
+export async function unit({ positional }) {
+    const root = requireProjectRoot();
+    const featuresRoot = path.join(root, "src", "features");
+    const name = positional[0] || (await pickDirectory("feature", featuresRoot));
+    await scaffold("feature", "unit", { name, pascalName: pascalCase(name) }, { cwd: root });
+}
+export async function action({ positional, flags, }) {
+    const root = requireProjectRoot();
+    const featuresRoot = path.join(root, "src", "features");
+    const feature = positional[0] || (await pickDirectory("feature", featuresRoot));
+    const name = positional[1] ||
+        (typeof flags.name === "string" ? flags.name : undefined) ||
+        (await askName("Action name (PascalCase)"));
+    await scaffold("feature", "action", {
+        feature,
+        name: pascalCase(name),
+        pascalName: pascalCase(name),
+        rawName: name,
+    }, { cwd: root });
+}
+export async function multicast({ positional, flags, }) {
+    const root = requireProjectRoot();
+    const featuresRoot = path.join(root, "src", "features");
+    const feature = positional[0] || (await pickDirectory("feature", featuresRoot));
+    const name = positional[1] ||
+        (typeof flags.name === "string" ? flags.name : undefined) ||
+        (await askName("Multicast action (PascalCase)"));
+    await scaffold("feature", "multicast", {
+        feature,
+        featurePascal: pascalCase(feature),
+        name: pascalCase(name),
+        pascalName: pascalCase(name),
+        rawName: name,
+    }, { cwd: root });
+}

package/dist/cli/lib/commands/index.js

@@ -0,0 +1,89 @@
+import * as init from "./init/index.js";
+import * as app from "./app/index.js";
+import * as feature from "./feature/index.js";
+import * as shared from "./shared/index.js";
+export const tree = {
+    init: {
+        leaf: true,
+        description: "Bootstrap a new March Hare project",
+        run: init.run,
+    },
+    app: {
+        leaf: false,
+        description: "Manage the host (pages, integration tests, actions)",
+        children: {
+            new: {
+                leaf: true,
+                description: "Create a new page under app/pages/",
+                run: app.newPage,
+            },
+            integration: {
+                leaf: true,
+                description: "Add an integration test for an existing page",
+                run: app.integration,
+            },
+            action: {
+                leaf: true,
+                description: "Add a new action handler to an existing page",
+                run: app.action,
+            },
+        },
+    },
+    feature: {
+        leaf: false,
+        description: "Manage features (slices, unit tests, actions)",
+        children: {
+            new: {
+                leaf: true,
+                description: "Create a new feature slice",
+                run: feature.newFeature,
+            },
+            unit: {
+                leaf: true,
+                description: "Add a unit test next to an existing feature",
+                run: feature.unit,
+            },
+            action: {
+                leaf: true,
+                description: "Add a new action handler to an existing feature",
+                run: feature.action,
+            },
+            multicast: {
+                leaf: true,
+                description: "Add a multicast action to an existing feature's Scope",
+                run: feature.multicast,
+            },
+        },
+    },
+    shared: {
+        leaf: false,
+        description: "Manage shared building blocks",
+        children: {
+            component: {
+                leaf: true,
+                description: "Create a new shared component",
+                run: shared.component,
+            },
+            resource: {
+                leaf: true,
+                description: "Create a new shared resource",
+                run: shared.resource,
+            },
+            util: {
+                leaf: true,
+                description: "Create a new shared utility",
+                run: shared.util,
+            },
+            type: {
+                leaf: true,
+                description: "Add a shared type/payload/broadcast namespace",
+                run: shared.type,
+            },
+            unit: {
+                leaf: true,
+                description: "Add a unit test next to an existing shared module",
+                run: shared.unit,
+            },
+        },
+    },
+};

package/dist/cli/lib/commands/init/index.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import process from "node:process";
+import kleur from "kleur";
+import { pascalCase } from "change-case";
+import { scaffold } from "../../runner/index.js";
+import { askName, askDescription } from "../../prompt/index.js";
+export async function run({ positional, flags }) {
+    const rawName = positional[0] ||
+        (typeof flags.name === "string" ? flags.name : undefined) ||
+        (await askName("Project name", "my-app"));
+    const description = (typeof flags.description === "string" ? flags.description : undefined) ||
+        (await askDescription("Short description", `A March Hare project: ${rawName}`));
+    const apiBase = (typeof flags.apiBase === "string" ? flags.apiBase : undefined) ||
+        (await askDescription("Default API base URL", "https://api.example.com"));
+    const cwd = path.resolve(process.cwd(), rawName);
+    const env = pascalCase(rawName);
+    console.log();
+    console.log(kleur.bold(`  Scaffolding ${kleur.magenta(rawName)} into ${kleur.gray(cwd)}`));
+    console.log();
+    await scaffold("init", "new", { name: rawName, description, apiBase, env }, { cwd });
+    console.log();
+    console.log(kleur.green("  Project ready."));
+    console.log();
+    console.log(kleur.bold("  Next steps:"));
+    console.log(`    cd ${rawName}`);
+    console.log("    yarn install");
+    console.log("    yarn dev");
+    console.log();
+}

package/dist/cli/lib/commands/shared/index.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+import kleur from "kleur";
+import { select } from "@inquirer/prompts";
+import { pascalCase } from "change-case";
+import { scaffold } from "../../runner/index.js";
+import { askName, pickDirectory, requireProjectRoot, } from "../../prompt/index.js";
+const sharedSubdirs = {
+    components: "component",
+    resources: "resource",
+    utils: "util",
+};
+export async function component({ positional }) {
+    const root = requireProjectRoot();
+    const name = positional[0] || (await askName("Component name (kebab-case)"));
+    await scaffold("shared", "component", { name, pascalName: pascalCase(name) }, { cwd: root });
+}
+export async function resource({ positional }) {
+    const root = requireProjectRoot();
+    const name = positional[0] || (await askName("Resource name (kebab-case)"));
+    await scaffold("shared", "resource", { name, pascalName: pascalCase(name) }, { cwd: root });
+    console.log(kleur.dim(`\n  Remember to re-export from src/shared/resources/index.ts: export * as ${name.replace(/-/g, "")} from "./${name}/index.ts";`));
+}
+export async function util({ positional }) {
+    const root = requireProjectRoot();
+    const name = positional[0] || (await askName("Util name (kebab-case)"));
+    await scaffold("shared", "util", { name, pascalName: pascalCase(name) }, { cwd: root });
+}
+export async function type({ positional, flags }) {
+    const root = requireProjectRoot();
+    const kind = positional[0] ||
+        (typeof flags.kind === "string" ? flags.kind : undefined) ||
+        (await select({
+            message: "Kind of type to add",
+            choices: [
+                { name: "Payload — cross-feature data type", value: "payload" },
+                { name: "Broadcast — global action class", value: "broadcast" },
+            ],
+        }));
+    const name = positional[1] || (await askName(`${kind} name (kebab-case)`));
+    await scaffold("shared", `type-${kind}`, { name, pascalName: pascalCase(name) }, { cwd: root });
+}
+export async function unit({ positional }) {
+    const root = requireProjectRoot();
+    const sharedRoot = path.join(root, "src", "shared");
+    const kindKey = positional[0] ||
+        (await select({
+            message: "Which kind of shared module?",
+            choices: Object.keys(sharedSubdirs)
+                .filter((key) => fs.existsSync(path.join(sharedRoot, key)))
+                .map((key) => ({ name: key, value: key })),
+        }));
+    const dir = path.join(sharedRoot, kindKey);
+    const name = positional[1] || (await pickDirectory(kindKey, dir));
+    await scaffold("shared", `unit-${sharedSubdirs[kindKey]}`, { name, pascalName: pascalCase(name), kind: kindKey }, { cwd: root });
+}

package/dist/cli/lib/index.js

@@ -0,0 +1,56 @@
+import process from "node:process";
+import kleur from "kleur";
+import { select } from "@inquirer/prompts";
+import { banner } from "./banner/index.js";
+import { tree } from "./commands/index.js";
+import { parseInvocation } from "./parser/index.js";
+async function selectChild(branch) {
+    const choices = Object.entries(branch.children).map(([key, child]) => ({
+        name: child.leaf
+            ? `${kleur.bold(key).padEnd(16)} ${kleur.gray(child.description)}`
+            : `${kleur.bold(key).padEnd(16)} ${kleur.gray(`${child.description} ›`)}`,
+        value: key,
+    }));
+    return select({ message: "What would you like to do?", choices });
+}
+function printTree(branch) {
+    console.log(kleur.dim("Available sub-commands:"));
+    Object.entries(branch.children).forEach(([key, child]) => {
+        const arrow = child.leaf ? "  " : " ›";
+        console.log(`  ${kleur.bold(key).padEnd(14)} ${kleur.gray(child.description)}${arrow}`);
+    });
+}
+async function descend(node, positional, flags) {
+    if (node.leaf) {
+        return node.run({ positional, flags });
+    }
+    const [next, ...rest] = positional;
+    if (next && node.children[next]) {
+        return descend(node.children[next], rest, flags);
+    }
+    if (next) {
+        console.error(kleur.red(`Unknown command: ${next}`));
+        printTree(node);
+        process.exit(1);
+    }
+    const choice = await selectChild(node);
+    return descend(node.children[choice], rest, flags);
+}
+function rootBranch(children) {
+    return { leaf: false, description: "root", children };
+}
+export async function main(argv) {
+    const { positionals, flags } = parseInvocation(argv);
+    if (flags.help || positionals[0] === "help") {
+        banner();
+        console.log(kleur.bold("Usage:"), "mh [command] [sub-command] [name] [--flag=value]");
+        console.log();
+        printTree(rootBranch(tree));
+        console.log();
+        console.log(kleur.dim("Run a command with no name to be prompted interactively."));
+        console.log(kleur.dim("Run `mh` alone for a menu of all commands."));
+        return;
+    }
+    banner();
+    await descend(rootBranch(tree), [...positionals], flags);
+}

package/dist/cli/lib/parser/index.js

@@ -0,0 +1,24 @@
+import { parseArgs } from "node:util";
+import { config } from "../utils.js";
+function splitNegations(args) {
+    return args.reduce((acc, token) => token.startsWith("--no-")
+        ? {
+            rest: acc.rest,
+            negations: { ...acc.negations, [token.slice(5)]: false },
+        }
+        : { rest: [...acc.rest, token], negations: acc.negations }, { rest: [], negations: {} });
+}
+export function parseInvocation(argv) {
+    const { rest, negations } = splitNegations(argv);
+    const { values, positionals } = parseArgs({
+        args: rest,
+        options: config.options,
+        allowPositionals: true,
+        strict: false,
+        tokens: false,
+    });
+    return {
+        positionals,
+        flags: { ...values, ...negations },
+    };
+}

package/dist/cli/lib/prompt/index.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { input, select, confirm } from "@inquirer/prompts";
+import kleur from "kleur";
+import { findUpSync } from "find-up";
+import { kebabCase } from "change-case";
+import { config } from "../utils.js";
+export async function askName(message, fallback) {
+    const value = await input({
+        message,
+        default: fallback,
+        validate: (raw) => {
+            const slug = kebabCase(raw);
+            if (!slug)
+                return "Name is required";
+            if (!/^[a-z][a-z0-9-]*$/.test(slug)) {
+                return "Use lowercase letters, digits and hyphens (e.g. add-cat)";
+            }
+            return true;
+        },
+    });
+    return kebabCase(value);
+}
+export async function askDescription(message, fallback = "") {
+    return input({ message, default: fallback });
+}
+export async function askConfirm(message, def = true) {
+    return confirm({ message, default: def });
+}
+export async function pickDirectory(label, root) {
+    if (!fs.existsSync(root)) {
+        throw new Error(`${label} root not found: ${root}. Run \`mh init <name>\` first.`);
+    }
+    const entries = fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .toSorted();
+    if (entries.length === 0) {
+        throw new Error(`No ${label} found under ${path.relative(process.cwd(), root)}.`);
+    }
+    return select({
+        message: `Pick a ${label}`,
+        choices: entries.map((name) => ({ name, value: name })),
+    });
+}
+export function findProjectRoot(startCwd = process.cwd()) {
+    const marker = findUpSync((directory) => config.projectMarkers.every((relative) => fs.existsSync(path.join(directory, relative)))
+        ? directory
+        : undefined, { cwd: startCwd, type: "directory" });
+    return marker ?? null;
+}
+export function requireProjectRoot() {
+    const root = findProjectRoot();
+    if (!root) {
+        console.error(kleur.red("Could not find a March Hare project root. Run inside a project created with `mh init <name>`."));
+        process.exit(1);
+    }
+    return root;
+}

package/dist/cli/lib/runner/index.js

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import ejs from "ejs";
+import kleur from "kleur";
+import { glob } from "tinyglobby";
+import { helpers, parseTemplate, renderCondition, renderForce, writeFile, injectInto, } from "./utils.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const templates = path.resolve(here, "..", "..", "templates");
+export async function scaffold(generator, action, vars, { cwd = process.cwd() } = {}) {
+    const root = path.join(templates, generator, action);
+    if (!fs.existsSync(root)) {
+        throw new Error(`Unknown generator: ${generator}/${action}`);
+    }
+    const data = { ...helpers, h: helpers, ...vars };
+    const files = await glob(["**/*.ejs.t"], { cwd: root, absolute: true });
+    const initial = { written: [], skipped: [], injected: [] };
+    const result = files.reduce((acc, file) => {
+        const raw = fs.readFileSync(file, "utf8");
+        const { meta, body } = parseTemplate(raw);
+        if (!meta.to)
+            return acc;
+        const target = path.resolve(cwd, ejs.render(meta.to, data));
+        if (!renderCondition(meta.if, data)) {
+            return { ...acc, skipped: [...acc.skipped, path.relative(cwd, target)] };
+        }
+        const rendered = ejs.render(body, data, { filename: file });
+        if (meta.inject) {
+            injectInto(target, rendered, meta, data);
+            return {
+                ...acc,
+                injected: [...acc.injected, path.relative(cwd, target)],
+            };
+        }
+        if (fs.existsSync(target) && !renderForce(meta.force, data)) {
+            return { ...acc, skipped: [...acc.skipped, path.relative(cwd, target)] };
+        }
+        writeFile(target, rendered);
+        return { ...acc, written: [...acc.written, path.relative(cwd, target)] };
+    }, initial);
+    result.written.forEach((file) => console.log(kleur.green("    added"), file));
+    result.injected.forEach((file) => console.log(kleur.cyan("  injected"), file));
+    result.skipped.forEach((file) => console.log(kleur.yellow("   skipped"), file));
+    return result;
+}

package/dist/cli/lib/runner/types.js

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

package/dist/cli/lib/runner/utils.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import ejs from "ejs";
+import { kebabCase, pascalCase, camelCase, capitalCase } from "change-case";
+export const helpers = {
+    kebab: kebabCase,
+    pascal: pascalCase,
+    camel: camelCase,
+    title: capitalCase,
+};
+export function parseTemplate(source) {
+    const parsed = matter(source, { delimiters: ["---", "---"] });
+    return {
+        meta: parsed.data,
+        body: parsed.content.replace(/^\n/, ""),
+    };
+}
+export function isTruthy(value) {
+    return value === true || value === "true" || value === "yes";
+}
+export function renderCondition(expr, data) {
+    if (!expr)
+        return true;
+    return isTruthy(ejs.render(`<%= ${expr} %>`, data));
+}
+export function renderForce(expr, data) {
+    if (!expr)
+        return false;
+    return isTruthy(ejs.render(`<%= ${expr} %>`, data));
+}
+export function writeFile(target, content) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, "utf8");
+}
+export function injectInto(target, content, meta, data) {
+    if (!fs.existsSync(target)) {
+        writeFile(target, content);
+        return;
+    }
+    const original = fs.readFileSync(target, "utf8");
+    if (meta.skip_if) {
+        const pattern = new RegExp(ejs.render(meta.skip_if, data), "m");
+        if (pattern.test(original))
+            return;
+    }
+    if (meta.after) {
+        const pattern = new RegExp(ejs.render(meta.after, data), "m");
+        const updated = original.replace(pattern, (match) => `${match}\n${content}`);
+        fs.writeFileSync(target, updated, "utf8");
+        return;
+    }
+    if (meta.before) {
+        const pattern = new RegExp(ejs.render(meta.before, data), "m");
+        const updated = original.replace(pattern, (match) => `${content}\n${match}`);
+        fs.writeFileSync(target, updated, "utf8");
+        return;
+    }
+    fs.writeFileSync(target, `${original}\n${content}`, "utf8");
+}

package/dist/cli/lib/types.js

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

package/dist/cli/lib/utils.js

@@ -0,0 +1,20 @@
+export const config = {
+    options: {
+        help: { type: "boolean", short: "h" },
+        name: { type: "string" },
+        description: { type: "string" },
+        apiBase: { type: "string" },
+        heading: { type: "string" },
+        tagline: { type: "string" },
+        kind: { type: "string" },
+        stateful: { type: "boolean" },
+        presentational: { type: "boolean" },
+    },
+    banner: {
+        title: "March Hare",
+        tagline: "We're all mad here.",
+        subtitle: "— scaffold tool for March Hare projects",
+        font: "Slant",
+    },
+    projectMarkers: ["package.json", "src/app"],
+};

package/dist/cli/templates/app/action/actions.ts.ejs.t

@@ -0,0 +1,10 @@
+---
+to: src/app/pages/<%= page %>/actions.ts
+inject: true
+before: ^\s*return actions;
+skip_if: Actions\.<%= pascalName %>
+---
+  actions.useAction(Actions.<%= pascalName %>, (_context) => {
+    // TODO: handle the <%= pascalName %> action
+  });
+

package/dist/cli/templates/app/action/types.ts.ejs.t

@@ -0,0 +1,7 @@
+---
+to: src/app/pages/<%= page %>/types.ts
+inject: true
+after: ^export class Actions \{$
+skip_if: <%= pascalName %>
+---
+  static <%= pascalName %> = Action("<%= rawName %>");

package/dist/cli/templates/app/integration/index.integration.tsx.ejs.t

@@ -0,0 +1,13 @@
+---
+to: src/app/pages/<%= name %>/index.integration.tsx
+---
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import { Root } from "@app/index.tsx";
+
+describe("<%= pascalName %>Page (integration)", () => {
+  it("mounts inside the app boundary without crashing", () => {
+    render(<Root />);
+    expect(document.body).toBeInTheDocument();
+  });
+});

package/dist/cli/templates/app/page/actions.ts.ejs.t

@@ -0,0 +1,14 @@
+---
+to: src/app/pages/<%= name %>/actions.ts
+---
+import { app } from "../../utils.ts";
+import { Actions, type Model } from "./types.ts";
+
+export function useActions() {
+  const context = app.useContext<Model, typeof Actions>();
+  const actions = context.useActions({ ready: false });
+
+  actions.useAction(Actions.Ready, context.with.always("ready", true));
+
+  return actions;
+}

package/dist/cli/templates/app/page/index.tsx.ejs.t

@@ -0,0 +1,20 @@
+---
+to: src/app/pages/<%= name %>/index.tsx
+---
+import * as React from "react";
+import { useActions } from "./actions.ts";
+import * as styles from "./styles.ts";
+
+export function <%= pascalName %>Page(): React.ReactElement {
+  const [model] = useActions();
+
+  return (
+    <main className={styles.layout}>
+      <header className={styles.header}>
+        <h1 className={styles.title}><%= heading %></h1>
+        <p className={styles.tagline}><%= tagline %></p>
+      </header>
+      <p>Model says: {JSON.stringify(model)}</p>
+    </main>
+  );
+}

package/dist/cli/templates/app/page/styles.ts.ejs.t

@@ -0,0 +1,35 @@
+---
+to: src/app/pages/<%= name %>/styles.ts
+---
+import { css } from "@emotion/css";
+import { colour, font, spacing } from "@shared/theme/index.ts";
+
+export const layout = css`
+  min-height: 100vh;
+  padding: ${spacing.xxl} ${spacing.l};
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: ${spacing.xl};
+  font-family: ${font.family};
+`;
+
+export const header = css`
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: ${spacing.xs};
+`;
+
+export const title = css`
+  margin: 0;
+  font-size: ${font.size.xxl};
+  font-weight: ${font.weight.bold};
+  color: ${colour.text.primary};
+`;
+
+export const tagline = css`
+  margin: 0;
+  color: ${colour.text.secondary};
+  font-size: ${font.size.m};
+`;

package/dist/cli/templates/app/page/types.ts.ejs.t

@@ -0,0 +1,12 @@
+---
+to: src/app/pages/<%= name %>/types.ts
+---
+import { Action } from "march-hare";
+
+export type Model = {
+  ready: boolean;
+};
+
+export class Actions {
+  static Ready = Action("<%= pascalName %>.Ready");
+}

package/dist/cli/templates/feature/action/actions.ts.ejs.t

@@ -0,0 +1,10 @@
+---
+to: src/features/<%= feature %>/actions.ts
+inject: true
+before: ^\s*return actions;
+skip_if: Actions\.<%= pascalName %>
+---
+  actions.useAction(Actions.<%= pascalName %>, (_context) => {
+    // TODO: handle <%= pascalName %>
+  });
+

package/dist/cli/templates/feature/action/types.ts.ejs.t

@@ -0,0 +1,7 @@
+---
+to: src/features/<%= feature %>/types.ts
+inject: true
+after: ^export class Actions \{$
+skip_if: <%= pascalName %>
+---
+  static <%= pascalName %> = Action("<%= rawName %>");

package/dist/cli/templates/feature/multicast/types.ts.ejs.t

@@ -0,0 +1,7 @@
+---
+to: src/features/<%= feature %>/types.ts
+inject: true
+after: ^export class Multicast \{$
+skip_if: <%= pascalName %>
+---
+  static <%= pascalName %> = Action<unknown>("<%= rawName %>", Distribution.Multicast);