@abcnews/aunty 17.0.0-next.4 → 17.0.0-next.5

package/CONTRIBUTING.md

@@ -20,35 +20,19 @@ To revert to your original global install, run:
 npm unlink
 ```
 
+For ease of use, you can use the Aunty version directly with `node <path to aunty repo> -h`.
+
 ## Releasing new versions of `@abcnews/aunty`
 
-Releases are managed by `release-it`. To release a new version of aunty from the default branch, run:
+Releases are managed by `np`. To release a new version of aunty from the default branch, run:
 
-```
+```bash
 npm run release
 ```
 
-By default this will do the following:
-
-1. Bump the `patch` version in `package.json` (and `package-lock.json` if it exists)
-2. Commit and tag that version.
-3. Push the tag & commit to GitHub
-4. Publish to npm
-
-If you want to cut a minor or major release, run either of the following commands instead:
-
-```
-npm run release -- minor
-npm run release -- major
-```
-
-If you're ever unsure about what will happen, you can perform a dry run (which logs to the console) by running:
-
-```
-npm run release -- --dry-run
-```
+This will run tests, prompt you to select the version increment, and then publish to npm, commit, tag, and push to GitHub.
 
-View the [`release-it` docs](https://www.npmjs.com/package/release-it) for full usage examples, including pre-release and npm tag management.
+For more information, see the [`np` documentation](https://github.com/sindresorhus/np).
 
 ## Style
 

package/README.md

@@ -3,3 +3,26 @@
 A toolkit for working with ABC News projects
 
 THIS IS A NEW BRANCH FOR AUNTY@NEXT PLEASE BITE OFF A CHUNK OF WORK AND MERGE INTO the `aunty-next` BRANCH
+
+# Contributing
+
+The repo is split up by commands. You should be able to jump into the command you're interested in, and follow the logic from start to finish.
+
+### Command Entry Points
+
+- [build](./src/commands/build/index.ts)
+- [create](./src/commands/create/index.ts) (aliased as `new`)
+- [deploy](./src/commands/deploy/index.ts)
+- [release](./src/commands/release/index.ts)
+- [release-check](./src/commands/release-check/index.ts)
+- [serve](./src/commands/serve/index.ts)
+
+Aunty uses the pattern of "helpers" to abstract complex logic out and hopefully make our main entrypoints flat and readable.
+
+The main CLI logic is in [src/bin/commander.ts](./src/bin/commander.ts).
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for specifics.
+
+# Templates
+
+`aunty create` uses a custom template system to create new projects. See [TEMPLATES.md](./TEMPLATES.md) for specifics.

package/TEMPLATES.md

@@ -0,0 +1,112 @@
+`aunty create` uses a custom template system to create new projects. Templates have three main components:
+
+1. a programmatic index that uses clack prompts to ask for desired configuration
+2. a base template containing the dir to copy from + a programmatic script to perform the copy and any other tweaks
+3. a series of "patches" containing programmatic scripts to copy over additional files or make changes to the base template.
+
+The intention is to make this followable in logic, so you don't need any prior knowledge to make a new template. Hopefully this is helpful.
+
+## Guide to making a new template
+
+The following steps will guide you through creating a new template from scratch.
+
+### 1. Scaffold your starting point
+
+It's usually easier to start with a working scaffold than writing a project framework from scratch.
+
+1. Generate your base project in a temporary folder using standard initialization tools (e.g., `npm create vite@latest`).
+2. Test the generated project to ensure it works as expected before converting it into a template.
+
+### 2. Create the Base Template
+
+Now you need to bring those scaffolded files into the Aunty project.
+
+1. Create the directory structure for your template's base contents: `templates/<your-template>/base/contents`.
+2. Copy your scaffolded project files into this `contents/` directory.
+3. **Rename `.gitignore` to `_gitignore`**.
+
+**Note:** NPM drops `.gitignore` files by default during package publishing. If you don't rename it, the file won't be included when Aunty is installed. Aunty's initialization helper will automatically rename it back to `.gitignore` when a user creates a new project.
+
+### 3. Create the Base Init Script
+
+Next, you need a script to copy those base files to the user's destination directory.
+
+1. Create `templates/<your-template>/base/init.ts`.
+2. Export an `init(options: InitOptions)` function.
+3. Use the built-in helper functions (from [`src/lib/initHelpers.ts`](./src/lib/initHelpers.ts)) to copy the contents and install Aunty as a dependency.
+
+```typescript
+import path from "node:path";
+import { copyContents, installAunty } from "../../../src/lib/initHelpers.ts";
+import type { InitOptions } from "../../../src/commands/create/types.ts";
+
+export async function init(options: InitOptions) {
+  // Copy the files from base/contents to the new project directory
+  await copyContents(path.join(import.meta.dirname, "contents"), options.dir);
+
+  // Ensure @abcnews/aunty is added to the devDependencies
+  await installAunty(options.dir);
+}
+```
+
+### 4. Create the Main Entry Point
+
+The entry point handles the user flow, asking any required questions before calling the init script.
+
+1. Create `templates/<your-template>/index.ts`.
+2. Export a default `run(options: InitOptions)` function.
+3. Use [`@clack/prompts`](https://github.com/natemoo-re/clack/tree/main/packages/prompts) to gather user preferences (e.g., confirm if they want TypeScript, or select a variant).
+4. Invoke your base `init.ts` script.
+
+```typescript
+import { confirm, isCancel, cancel } from "@clack/prompts";
+import type { InitOptions } from "../../src/commands/create/types.ts";
+import { init as baseInit } from "./base/init.ts";
+import { init as jsInit } from "./patch-js/init.ts";
+
+export default async function run(options: InitOptions) {
+  const useTypescript = await confirm({
+    message: "Do you want to use TypeScript?",
+    initialValue: true,
+  });
+
+  if (isCancel(useTypescript)) {
+    cancel("Operation cancelled.");
+    return 1;
+  }
+
+  // 1. Run the base setup first
+  await baseInit(options);
+
+  // 2. Apply patches conditionally based on user answers
+  if (!useTypescript) {
+    await jsInit(options);
+  }
+
+  return 0;
+}
+```
+
+### 5. Create Patches (Optional)
+
+If your template requires variants (e.g., an Odyssey version vs a standard version, or JS vs TS), you can create "patches".
+
+1. Create a patch directory (e.g., `templates/<your-template>/patch-js/contents` and `templates/<your-template>/patch-js/init.ts`).
+2. Patches are just smaller init scripts that layer extra files, string replacements, or `package.json` edits on top of the base template.
+3. Invoke the patch's `init` function in your main `index.ts` conditionally, as demonstrated in the snippet in Step 4.
+
+### 6. Test Locally
+
+While developing your new template, you can test it locally by running the CLI from the root of the Aunty repository:
+
+```bash
+node . create
+```
+
+or, in another dir with
+
+```bash
+node ../aunty create
+```
+
+This will invoke your local version of Aunty, allowing you to test the prompt flow and verify the generated output in your chosen destination directory.

package/eslint.config.mjs

@@ -3,5 +3,10 @@ import tseslint from 'typescript-eslint';
 
 export default [
   js.configs.recommended,
-  ...tseslint.configs.recommended
+  ...tseslint.configs.recommended,
+  {
+    "env": {
+      "node": true,
+    }
+  }
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abcnews/aunty",
-  "version": "17.0.0-next.4",
+  "version": "17.0.0-next.5",
   "type": "module",
   "description": "ABC News Digital developer toolkit",
   "repository": {
@@ -15,34 +15,43 @@
     "Ash Kyd <kyd.ashley@abc.net.au>"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "esbuild src/bin/commander.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/bin/commander.js",
+    "prepublishOnly": "npm run build",
     "dev": "tsx src/bin/aunty.ts",
-    "test": "echo \"Put your tests here\" && exit 1",
+    "test": "node --experimental-test-module-mocks --import tsx --test test/*.test.ts",
     "lint": "eslint src",
     "clean": "rimraf dist",
-    "prebuild": "npm run clean"
+    "prebuild": "npm run clean",
+    "release": "np"
   },
   "publishConfig": {
     "access": "public"
   },
-  "main": "src/bin/aunty.ts",
+  "main": "src/bin/aunty.js",
+  "exports": {
+    ".": "./src/bin/aunty.js",
+    "./vite": "./src/lib/vite.ts"
+  },
   "bin": {
-    "aunty": "src/bin/aunty.ts",
-    "nt": "src/bin/aunty.ts"
+    "aunty": "src/bin/aunty.js",
+    "nt": "src/bin/aunty.js"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/async": "^3.2.25",
     "@types/fs-extra": "^11.0.4",
+    "@types/lodash-es": "^4.17.12",
     "@types/node": "^25.0.10",
+    "@types/semver": "^7.7.1",
+    "esbuild": "^0.28.1",
     "eslint": "^9.39.2",
     "install": "^0.13.0",
+    "np": "^12.0.0",
     "npm": "^11.11.1",
     "rimraf": "^6.1.2",
-    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.54.0"
   },
@@ -51,10 +60,16 @@
     "async": "^3.2.6",
     "basic-ftp": "^5.2.0",
     "commander": "^14.0.3",
-    "ora": "^9.3.0",
+    "lodash-es": "^4.17.23",
     "picocolors": "^1.1.1",
+    "semver": "^7.8.5",
     "slugify": "^1.6.8",
     "tsx": "^4.21.0",
     "zx": "^8.8.5"
+  },
+  "allowScripts": {
+    "esbuild@0.28.1": true,
+    "esbuild@0.27.7": true,
+    "fsevents@2.3.3": true
   }
 }

package/src/bin/aunty.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+/**
+ * @file Aunty CLI Entry Point
+ * 
+ * This is the main file that launches Aunty. It handles:
+ * - Deferring to the locally installed version if available
+ * - Deciding whether to use the built JS in prod, or `tsx` in dev-like environments
+ *
+ * This file MUST be plain JavaScript to ensure compatibility as a CLI entry point.
+ */
+
+import { existsSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { $ } from "zx";
+
+const filename = fileURLToPath(import.meta.url);
+const dirname = path.dirname(filename);
+
+/**
+ * Bootstrap the CLI by preferring a local version if it exists.
+ */
+async function run() {
+  const localAuntyPath = path.join(
+    process.cwd(),
+    "node_modules/@abcnews/aunty/src/bin/aunty.js",
+  );
+
+  // If a local version exists and we are not it, prefer the local version.
+  // Do not defer to local version for the 'migrate' command, as it is used to upgrade the project.
+  const isMigrate = process.argv.includes("migrate");
+  if (
+    !isMigrate &&
+    existsSync(localAuntyPath) &&
+    (await realpath(localAuntyPath)) !== (await realpath(filename))
+  ) {
+    const result = await $({ stdio: "inherit", nothrow: true })`${process.execPath} ${localAuntyPath} ${process.argv.slice(2)}`;
+    process.exit(result.exitCode);
+  }
+
+  // Resolve paths for the built JS and original TS commander files.
+  const builtCommanderPath = path.resolve(dirname, "../../dist/bin/commander.js");
+  const commanderPath = path.resolve(dirname, "commander.ts");
+
+  let execPath;
+  let execArgs;
+
+  /** If running from node_modules, we are almost certainly running in prod  */
+  const isRunningFromNodeModules = filename.includes("node_modules");
+
+  if (isRunningFromNodeModules && existsSync(builtCommanderPath)) {
+    // If the built files are available and we are executing from node_modules, use those directly with node
+    execPath = process.execPath;
+    execArgs = [builtCommanderPath, ...process.argv.slice(2)];
+  } else {
+    // Otherwise run the package via tsx
+    // This is hit for local dev or when running straight from a Github branch
+    const localTsx = path.resolve(dirname, "../../node_modules/.bin/tsx");
+    execPath = existsSync(localTsx) ? localTsx : "tsx";
+    execArgs = [commanderPath, ...process.argv.slice(2)];
+  }
+
+  const result = await $({ stdio: "inherit", nothrow: true })`${execPath} ${execArgs}`;
+  process.exit(result.exitCode);
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/bin/commander.ts

@@ -0,0 +1,174 @@
+/**
+ * @file
+ * Core CLI logic using Commander.js.
+ */
+
+import path from "node:path";
+import { Command, Help } from "commander";
+import { run as runDeploy } from "../commands/deploy/index.ts";
+import { run as runReleaseCheck } from "../commands/release-check/index.ts";
+import { run as runRelease } from "../commands/release/index.ts";
+import { run as runCreate } from "../commands/create/index.ts";
+import { run as runBuild } from "../commands/build/index.ts";
+import { run as runServe } from "../commands/serve/index.ts";
+import { run as runMigrate } from "../commands/migrate/index.ts";
+import { getHeader, printDevColours } from "../lib/terminal.ts";
+import { loadJson } from "../lib/util.ts";
+import pc from "picocolors";
+import rawColours from "../lib/colours.json" with { type: "json" };
+
+interface Colours {
+  commands: Record<string, string>;
+}
+
+const colours = rawColours as unknown as Colours;
+const pcColors = pc as unknown as Record<string, (str: string) => string>;
+
+const pkgPath = path.join(import.meta.dirname, "../../package.json");
+const pkg = (await loadJson(pkgPath)) as {
+  version: string;
+  name: string;
+  description: string;
+};
+const version = pkg?.version || "0.0.0";
+
+const program = new Command();
+
+program
+  .name("aunty")
+  .description(
+    getHeader(
+      `${pkg.name}${pc.dim("@" + pkg.version)}`,
+      `${pc.dim(pkg.description.slice(0, 73))}`,
+      { prepend: "" },
+    ) +
+      "\n" +
+      pc.dim("─".repeat(80)),
+  )
+  .version(version);
+
+/**
+ * Configures the CLI help output to colorise subcommand terms (e.g. 'deploy', 'create')
+ * in their designated project palette colors defined in colours.json.
+ */
+program.configureHelp({
+  subcommandTerm: (cmd) => {
+    const name = cmd.name();
+    const colourName = colours.commands[name];
+    const colourFn =
+      colourName && typeof pcColors[colourName] === "function"
+        ? pcColors[colourName]
+        : (str: string) => str;
+    const term = new Help().subcommandTerm(cmd);
+    return term.replace(name, colourFn(name));
+  },
+  formatHelp: (cmd, helper) => {
+    const baseHelp = new Help().formatHelp(cmd, helper);
+    if (cmd.parent) {
+      const name = cmd.name();
+      const colourName = colours.commands[name] || "rainbow";
+      const logoHeader = getHeader("aunty", name, {
+        prepend: "",
+        colour: colourName,
+      });
+      return `${logoHeader}\n\n${baseHelp}`;
+    }
+    return baseHelp;
+  },
+});
+
+program
+  .command("deploy")
+  .description(
+    "Deploy the project to FTP. This deploys the current dist/ folder to the specified remote folder, falling back to the current version number. Use this to retry a failed release.",
+  )
+  .argument(
+    "[destDir]",
+    "Override the target folder name (defaults to package.json version)",
+  )
+  .option("-d, --dry-run", "Show what would happen without uploading", false)
+  .option("-f, --force", "Overwrite the remote directory if it exists", false)
+  .action(async (destDir, options) => {
+    process.exit(await runDeploy({ destDir, ...options }));
+  });
+
+program
+  .command("create")
+  .description("Create a new project from a template")
+  .argument("[destDir]", "Directory to create the project in")
+  .action(async (destDir) => {
+    process.exit(await runCreate(destDir));
+  });
+
+program
+  .command("new", { hidden: true })
+  .description("Alias for create")
+  .argument("[destDir]", "Directory to create the project in")
+  .action(async (destDir) => {
+    process.exit(await runCreate(destDir));
+  });
+
+program
+  .command("release-check")
+  .description("Perform pre-release checks")
+  .action(async () => {
+    process.exit(await runReleaseCheck());
+  });
+
+program
+  .command("release")
+  .description("Version and release your project to FTP")
+  .option("--version <version>", "Override the release version directly")
+  .action(async (options) => {
+    process.exit(await runRelease(options));
+  });
+
+program
+  .command("serve")
+  .description("Start a local development server")
+  .action(async () => {
+    await runServe();
+  });
+
+program
+  .command("build")
+  .description("Build the project for production")
+  .action(async () => {
+    process.exit(await runBuild());
+  });
+
+program
+  .command("migrate")
+  .description("Migrate a legacy project to use Vite and the latest version of aunty")
+  .option("-y, --yes", "Skip confirmation prompt", false)
+  .option("--skip-git", "Skip Git safety checks", false)
+  .action(async (options) => {
+    process.exit(await runMigrate(options));
+  });
+
+program
+  .command("dev-colours", { hidden: true })
+  .description("Test all available gradient colours")
+  .action(() => {
+    printDevColours();
+    process.exit(0);
+  });
+
+try {
+  // Start Commander
+  await program.parseAsync(process.argv);
+} catch (err: unknown) {
+  // If Commander throws, print our unhandled exception message
+  if (err instanceof Error) {
+    console.error(`${pc.dim(err.stack)}`);
+  } else {
+    console.error(`${pc.red(pc.bold("Error:"))} ${pc.red(`‘${String(err)}’`)}`);
+  }
+
+  console.error(
+    `${pc.red(pc.bold("■ Aunty has encountered an unhandled error."))}
+└ This is likely a bug. Please report it at: ${pc.cyan("https://github.com/abcnews/aunty/issues/new")}`,
+  );
+
+  process.exit(1);
+}

package/src/commands/build/index.ts

@@ -0,0 +1,23 @@
+import { intro, outro, log } from "@clack/prompts";
+import pc from "picocolors";
+import { getHeader } from "../../lib/terminal.ts";
+import { runBuild } from "../../lib/util.ts";
+
+/**
+ * The main entry point for the 'aunty build' command.
+ */
+export async function run(): Promise<number> {
+  intro(getHeader(pc.dim("aunty"), "build", { colour: "blue" }));
+  outro("Building project for production...");
+
+  try {
+    await runBuild({ stdio: "inherit" });
+    return 0;
+  } catch (err: any) {
+    if (err.exitCode !== undefined) {
+      return err.exitCode;
+    }
+    log.error(err.message || `Failed to start npm command: ${err.message}`);
+    return 1;
+  }
+}

package/src/commands/create/index.ts

@@ -0,0 +1,148 @@
+import {
+  intro,
+  outro,
+  text,
+  select,
+  confirm,
+  log,
+  cancel,
+  isCancel,
+} from "@clack/prompts";
+import path from "node:path";
+import fs from "node:fs/promises";
+import pc from "picocolors";
+import { $ } from "zx";
+import { getHeader, spin } from "../../lib/terminal.ts";
+import { isProjectNameAndVersionAvailable } from "../../lib/ftp.ts";
+import templates from "../../../templates/index.ts";
+
+/**
+ * The main entry point for the 'aunty create' command.
+ */
+export async function run(destDirArg?: string): Promise<number> {
+  intro(getHeader(pc.dim("aunty"), "create", { colour: "green" }));
+
+  // 1. Get project name
+  const projectName =
+    destDirArg ||
+    (await text({
+      message: "What is your project named?",
+      placeholder: destDirArg || "my-new-project",
+      validate: (value) => {
+        if (!value || value.length === 0) {
+          return "Project name is required";
+        }
+        if (!value.match(/^[a-z0-9-]+$/)) {
+          return "Project name should be lowercase-alphanumeric-with-hypens";
+        }
+      },
+    }));
+
+  if (isCancel(projectName)) {
+    cancel("Operation cancelled.");
+    return 0;
+  }
+
+  const finalProjectName = projectName || destDirArg || "my-new-project";
+  const projectDest = path.resolve(process.cwd(), finalProjectName);
+
+  // 1.5. Check FTP for name collision
+  const ftpSpinner = spin("Checking project name availability...");
+  const isAvailable = await isProjectNameAndVersionAvailable(finalProjectName);
+  ftpSpinner.stop("Project name checked");
+
+  if (isAvailable === "error") {
+    const shouldContinue = await confirm({
+      message: pc.red(
+        "Could not connect to FTP to check name availability. Continue anyway?",
+      ),
+      initialValue: true,
+    });
+    if (!shouldContinue || isCancel(shouldContinue)) {
+      cancel("Create cancelled.");
+      return 0;
+    }
+  }
+  if (isAvailable === "exists") {
+    const shouldContinue = await confirm({
+      message: pc.yellow(
+        `Project name "${finalProjectName}" already exists on FTP. Continue?`,
+      ),
+      initialValue: false,
+    });
+    if (!shouldContinue || isCancel(shouldContinue)) {
+      cancel("Create cancelled.");
+      return 0;
+    }
+  }
+
+  // 2. Select project type
+  const projectType = await select({
+    message: "Select a project type:",
+    options: templates.projects.map((p) => ({ value: p, label: p.name })),
+  });
+
+  if (isCancel(projectType)) {
+    cancel("Operation cancelled.");
+    return 0;
+  }
+
+  const selectedProject = projectType;
+
+  // 3. Create directory
+  if (
+    await fs
+      .access(projectDest)
+      .then(() => true)
+      .catch(() => false)
+  ) {
+    cancel(`Directory ${pc.cyan(projectDest)} already exists.`);
+    return 1;
+  }
+
+  // 4. Run initialization
+  try {
+    const exitCode = await selectedProject.run({
+      projectName: finalProjectName,
+      baseDir: projectDest,
+    });
+
+    if (exitCode !== 0) {
+      return 0;
+    }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    cancel(`Failed to create project: ${message}`);
+    if (err instanceof Error && err.stack) {
+      console.error(err.stack);
+    }
+    return 1;
+  }
+
+  // 7. NPM Install
+  const installSpinner = spin("Installing dependencies...");
+  try {
+    await $({ cwd: projectDest })`npm install`.quiet();
+    installSpinner.stop("Dependencies installed");
+  } catch {
+    installSpinner.cancel(
+      "Failed to install dependencies. You may need to run 'npm install' manually.",
+    );
+  }
+
+  // 8. Initialize Git Repository
+  try {
+    await $({ cwd: projectDest })`git init`.quiet();
+  } catch {}
+
+  log.step("Next steps:");
+  log.message(
+    `
+${pc.bold(1)}. cd ${finalProjectName}
+${pc.bold(2)}. npm run dev
+`.trim(),
+  );
+
+  outro("Happy coding.");
+  return 0;
+}