march-hare 0.12.1 → 0.13.1

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);

package/dist/cli/templates/feature/presentational/index.tsx.ejs.t

@@ -0,0 +1,14 @@
+---
+to: src/features/<%= name %>/index.tsx
+---
+import * as React from "react";
+import type { Props } from "./types.ts";
+import { scope } from "./utils.ts";
+
+export function <%= pascalName %>({ label }: Props): React.ReactElement {
+  return (
+    <scope.Boundary>
+      <span>{label}</span>
+    </scope.Boundary>
+  );
+}

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

@@ -0,0 +1,12 @@
+---
+to: src/features/<%= name %>/types.ts
+---
+import { Action, Distribution } from "march-hare";
+
+export type Props = {
+  label: string;
+};
+
+export class Multicast {
+  static Update = Action<string>("<%= pascalName %>.Update", Distribution.Multicast);
+}

package/dist/cli/templates/feature/presentational/utils.ts.ejs.t

@@ -0,0 +1,8 @@
+---
+to: src/features/<%= name %>/utils.ts
+---
+import { shared } from "march-hare";
+import { type Envs } from "@shared/types/index.ts";
+import type { Multicast } from "./types.ts";
+
+export const scope = shared.Scope<Envs, typeof Multicast>();

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

@@ -0,0 +1,16 @@
+---
+to: src/features/<%= name %>/actions.ts
+---
+import { Actions, type Model } from "./types.ts";
+import { scope } from "./utils.ts";
+
+export function useActions() {
+  const context = scope.useContext<Model, typeof Actions>();
+  const actions = context.useActions({ count: 0 });
+
+  actions.useAction(Actions.Tick, (context) => {
+    context.actions.produce(({ model }) => void (model.count += 1));
+  });
+
+  return actions;
+}

package/dist/cli/templates/feature/stateful/index.tsx.ejs.t

@@ -0,0 +1,19 @@
+---
+to: src/features/<%= name %>/index.tsx
+---
+import * as React from "react";
+import { useActions } from "./actions.ts";
+import { scope } from "./utils.ts";
+import { Actions } from "./types.ts";
+
+export function <%= pascalName %>(): React.ReactElement {
+  const [model, actions] = useActions();
+
+  return (
+    <scope.Boundary>
+      <button onClick={() => actions.dispatch(Actions.Tick)}>
+        <%= pascalName %> ({model.count})
+      </button>
+    </scope.Boundary>
+  );
+}

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

@@ -0,0 +1,16 @@
+---
+to: src/features/<%= name %>/types.ts
+---
+import { Action, Distribution } from "march-hare";
+
+export type Model = {
+  count: number;
+};
+
+export class Actions {
+  static Tick = Action("<%= pascalName %>.Tick");
+}
+
+export class Multicast {
+  static Update = Action<number>("<%= pascalName %>.Update", Distribution.Multicast);
+}

package/dist/cli/templates/feature/stateful/utils.ts.ejs.t

@@ -0,0 +1,8 @@
+---
+to: src/features/<%= name %>/utils.ts
+---
+import { shared } from "march-hare";
+import { type Envs } from "@shared/types/index.ts";
+import type { Multicast } from "./types.ts";
+
+export const scope = shared.Scope<Envs, typeof Multicast>();

package/dist/cli/templates/feature/unit/index.test.tsx.ejs.t

@@ -0,0 +1,21 @@
+---
+to: src/features/<%= name %>/index.test.tsx
+---
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import { App } from "march-hare";
+import { <%= pascalName %> } from "./index.tsx";
+import { type Envs } from "@shared/types/index.ts";
+
+const app = App<Envs>({ env: { apiBase: "https://api.example.test" } });
+
+describe("<%= pascalName %>", () => {
+  it("renders inside an app boundary", () => {
+    render(
+      <app.Boundary>
+        <<%= pascalName %> />
+      </app.Boundary>,
+    );
+    expect(document.body).toBeInTheDocument();
+  });
+});

package/dist/cli/templates/init/new/README.md.ejs.t

@@ -0,0 +1,48 @@
+---
+to: README.md
+---
+# <%= title(name) %>
+
+<%= description %>
+
+Built with [March Hare](https://github.com/Wildhoney/MarchHare) and the
+[`@march-hare/cli`](https://github.com/Wildhoney/MarchHare/tree/main/src/cli)
+scaffolder.
+
+## Layout
+
+```
+src/
+├── app/        ← the host. One App() declaration, one Boundary, all routes.
+├── features/   ← user-facing behaviours. Each feature owns its own scope.
+└── shared/     ← reusable building blocks: types, resources, theme, utils.
+```
+
+Layer boundaries are enforced by `eslint-plugin-boundaries` — imports
+flow strictly downward (`app → features → shared`).
+
+## Scripts
+
+| Command              | What it does                              |
+| -------------------- | ----------------------------------------- |
+| `yarn dev`           | Start the Vite dev server                 |
+| `yarn test`          | Run unit + integration tests with Vitest  |
+| `yarn test:e2e`      | Run Playwright end-to-end tests           |
+| `yarn typecheck`     | TypeScript with no emit                   |
+| `yarn lint`          | ESLint                                    |
+| `yarn checks`        | Format, lint, typecheck, and test         |
+
+## Scaffolding more
+
+With the CLI installed globally (`npm i -g @march-hare/cli`) or linked
+locally, drop new pages, features, and shared modules in:
+
+```bash
+mh                    # interactive menu
+mh feature new        # add a feature
+mh app new            # add a page
+mh shared component   # add a shared component
+```
+
+See the [CLI README](https://github.com/Wildhoney/MarchHare/tree/main/src/cli)
+for the full list.