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

package/.prettierrc

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

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "eslint.validate": [
+    "typescript"
+  ],
+}

package/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+## Contributing
+
+To contribute to the development of **aunty**, clone the project:
+
+```bash
+git clone git@github.com:abcnews/aunty.git
+```
+
+...then, from the project directory, run:
+
+```bash
+npm link
+```
+
+This will link the globally-available `aunty` command to your clone.
+
+To revert to your original global install, run:
+
+```bash
+npm unlink
+```
+
+## Releasing new versions of `@abcnews/aunty`
+
+Releases are managed by `release-it`. To release a new version of aunty from the default branch, run:
+
+```
+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
+```
+
+View the [`release-it` docs](https://www.npmjs.com/package/release-it) for full usage examples, including pre-release and npm tag management.
+
+## Style
+
+This project's codebase should be managed with [eslint](https://github.com/eslint/eslint) and [prettier](https://github.com/prettier/prettier). You should configure your editor to take advantage of this to maintain the code style specifed in `.eslintrc` and `.prettierrc`. If your editor has a format-on-save option and a Prettier plugin, even better!

package/eslint.config.mjs

@@ -0,0 +1,7 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default [
+  js.configs.recommended,
+  ...tseslint.configs.recommended
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abcnews/aunty",
-  "version": "17.0.0-next.2",
+  "version": "17.0.0-next.4",
   "type": "module",
   "description": "ABC News Digital developer toolkit",
   "repository": {
@@ -22,9 +22,6 @@
     "clean": "rimraf dist",
     "prebuild": "npm run clean"
   },
-  "files": [
-    "dist"
-  ],
   "publishConfig": {
     "access": "public"
   },
@@ -50,12 +47,14 @@
     "typescript-eslint": "^8.54.0"
   },
   "dependencies": {
+    "@clack/prompts": "^1.2.0",
     "async": "^3.2.6",
     "basic-ftp": "^5.2.0",
     "commander": "^14.0.3",
     "ora": "^9.3.0",
     "picocolors": "^1.1.1",
     "slugify": "^1.6.8",
+    "tsx": "^4.21.0",
     "zx": "^8.8.5"
   }
 }

package/scripts/postinstall.ts

@@ -0,0 +1,7 @@
+/**
+ * Put post-install scripts here.
+ * 
+ * Will run after `npm install`.
+ */
+
+console.log("Hello from postinstall!");

package/src/bin/aunty.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env tsx
 
 /**
  * Aunty - ABC News Digital developer toolkit

package/src/commands/deploy/fs.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Recursively gets a list of all files in a directory.
+ * @param dirPath Path to the directory
+ * @param baseDir Optional base directory to calculate relative paths from
+ * @returns Array of file info objects
+ */
+export async function getFileInventory(
+  dirPath: string,
+  baseDir: string = dirPath,
+): Promise<{ path: string; relPath: string; size: number }[]> {
+  const inventory: { path: string; relPath: string; size: number }[] = [];
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      inventory.push(...(await getFileInventory(fullPath, baseDir)));
+    } else if (entry.isFile()) {
+      const stats = await fs.stat(fullPath);
+      inventory.push({
+        path: fullPath,
+        relPath: path.relative(baseDir, fullPath),
+        size: stats.size,
+      });
+    }
+  }
+
+  return inventory;
+}

package/src/commands/deploy/ftp.ts

@@ -0,0 +1,141 @@
+import ftp from "basic-ftp";
+import os from "node:os";
+import path from "node:path";
+import { loadJson } from "../../lib/util.ts";
+import { spin } from "../../lib/terminal.ts";
+
+const CREDENTIALS_PATH = path.resolve(os.homedir(), ".abc-credentials");
+
+/**
+ * Loads credentials from ~/.abc-credentials
+ */
+async function getCredentials(): Promise<{
+  host: string;
+  username?: string;
+  password?: string;
+  port?: number;
+}> {
+  const credentials = (await loadJson(CREDENTIALS_PATH)) as {
+    contentftp?: {
+      host: string;
+      username?: string;
+      password?: string;
+      port?: number;
+    };
+  } | null;
+  const contentftp = credentials?.contentftp;
+  if (!contentftp) {
+    throw new Error(
+      `Credentials file not found or missing 'contentftp' at ${CREDENTIALS_PATH}`,
+    );
+  }
+  return contentftp;
+}
+
+/**
+ * A wrapper around basic-ftp to provide a cleaner interface for ABC news-projects deployments.
+ */
+export class FtpClient {
+  private ftpClient: ftp.Client;
+  private ensuredDirs: Set<string>;
+  private credentialsPromise: ReturnType<typeof getCredentials>;
+
+  constructor(verbose = false) {
+    this.ftpClient = new ftp.Client();
+    this.ensuredDirs = new Set();
+    this.credentialsPromise = getCredentials();
+    if (verbose) {
+      this.ftpClient.ftp.verbose = true;
+    }
+  }
+
+  /**
+   * Connect to the FTP server
+   */
+  async connect(timeout = 5000) {
+    // @ts-expect-error - basic-ftp context timeout is readonly but allows runtime assignment
+    this.ftpClient.ftp.timeout = timeout;
+    const credentials = await this.credentialsPromise;
+    await this.ftpClient.access({
+      host: credentials.host,
+      user: credentials.username,
+      password: credentials.password,
+      port: Number(credentials.port) || 21,
+      secure: false,
+    });
+  }
+
+  /**
+   * Check if a directory exists on the remote
+   */
+  async exists(remotePath: string) {
+    try {
+      const parent = path.dirname(remotePath);
+      const name = path.basename(remotePath);
+      const list = await this.ftpClient.list(parent);
+      return list.some((item) => item.name === name);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Upload a directory to a remote path
+   */
+  async uploadDir(
+    localDir: string,
+    remoteDir: string,
+    onProgress?: (info: {
+      name: string;
+      bytes: number;
+      bytesOverall: number;
+    }) => void,
+  ) {
+    if (onProgress) {
+      this.ftpClient.trackProgress(onProgress);
+    }
+    await this.ftpClient.ensureDir(remoteDir);
+    await this.ftpClient.uploadFromDir(localDir);
+  }
+
+  /**
+   * Ensure a remote directory exists (with local caching)
+   */
+  async ensureDir(remoteDir: string) {
+    if (this.ensuredDirs.has(remoteDir)) return;
+
+    await this.ftpClient.ensureDir(remoteDir);
+    this.ensuredDirs.add(remoteDir);
+  }
+
+  /**
+   * Close the connection
+   */
+  close() {
+    this.ftpClient.close();
+  }
+
+  /**
+   * Test the FTP connection.
+   */
+  async testConnection(
+    timeout = 5000,
+    spinner?: ReturnType<typeof spin>,
+  ): Promise<FtpClient> {
+    const s = spinner || spin("Testing credentials...");
+
+    try {
+      await this.connect(timeout);
+      if (spinner) {
+        s.message("Credentials verified");
+      } else {
+        s.stop("Credentials verified");
+      }
+      return this;
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      s.cancel(`Connection failed: ${message}.`);
+      throw error;
+    }
+  }
+}

package/src/commands/deploy/index.ts

@@ -0,0 +1,147 @@
+import { intro, outro, confirm, log, cancel } from "@clack/prompts";
+import path from "node:path";
+import pc from "picocolors";
+import { FtpClient } from "./ftp.ts";
+import { loadJson, formatSize } from "../../lib/util.ts";
+import { getHeader, spin } from "../../lib/terminal.ts";
+import { getFileInventory } from "./fs.ts";
+import { BUILD_DIRECTORY_NAME } from "../../lib/constants.ts";
+import slugify from "slugify";
+
+interface DeployOptions {
+  destDir?: string;
+  buildDir?: string;
+  dryRun?: boolean;
+  force?: boolean;
+}
+
+/**
+ * The main entry point for the 'aunty deploy' command.
+ */
+export async function run(options: DeployOptions = {}): Promise<number> {
+  const projectRoot = process.cwd();
+
+  intro(
+    getHeader(
+      pc.dim("aunty"),
+      `deploy${options.dryRun ? ` ${pc.cyan("[dry]")}` : ""}`,
+    ),
+  );
+
+  // 1. Load config
+  const config = (await loadJson(path.join(projectRoot, "package.json"))) as {
+    name: string;
+    version: string;
+  } | null;
+
+  if (!config) {
+    log.error(`package.json not found in ${projectRoot}`);
+    return 1;
+  }
+
+  const { name, version } = config;
+  if (!name || !version) {
+    cancel("Missing name or version in package.json");
+    return 1;
+  }
+
+  // 3. Construct target path
+  const localDir = path.resolve(
+    projectRoot,
+    options.buildDir || BUILD_DIRECTORY_NAME,
+  );
+  const nameSlug = (slugify as any)(name, { strict: true });
+  const targetFolder = options.destDir || version;
+  const remoteDir = `/www/res/sites/news-projects/${nameSlug}/${targetFolder}/`;
+  const publicUrl = `https://www.abc.net.au/res/sites/news-projects/${nameSlug}/${targetFolder}/`;
+  log.info(`${pc.bold("Remote dir:")} ${pc.dim(remoteDir)}`);
+
+  // 4. File Inventory & Size Check
+  let inventory;
+  try {
+    inventory = await getFileInventory(localDir);
+  } catch (err) {
+    cancel(
+      `Build directory not found at ${pc.cyan(localDir)}. Have you run the build command?`,
+    );
+    return 1;
+  }
+
+  if (inventory.length === 0) {
+    cancel(`Build directory is empty! Nothing to deploy.`);
+    return 1;
+  }
+
+  const list = inventory
+    .map((f) => `  ${pc.dim(f.relPath)} (${formatSize(f.size)})`)
+    .join("\n");
+  log.step(`Found ${pc.bold(inventory.length)} files to deploy:\n${list}`);
+
+  if (options.dryRun) {
+    outro(pc.green("Dry run complete. No files were uploaded."));
+    return 0;
+  }
+
+  // 5. Credential Test & Confirmation
+  const ftpClient = new FtpClient();
+  try {
+    await ftpClient.testConnection();
+  } catch (err) {
+    // FtpClient.testConnection() already handles UI feedback via its own spinner
+    return 1;
+  }
+
+  const exists = await ftpClient.exists(remoteDir);
+
+  if (exists && !options.force) {
+    // Close the connection before waiting on user input to avoid a socket timeout
+    ftpClient.close();
+
+    const shouldOverwrite = await confirm({
+      message: `${pc.red(`Directory ${pc.bold(remoteDir)} already exists.`)} Overwrite?`,
+      initialValue: false,
+    });
+
+    if (!shouldOverwrite || typeof shouldOverwrite === "symbol") {
+      cancel("Deploy cancelled.");
+      return 0;
+    }
+
+    // Reconnect after the prompt
+    await ftpClient.connect();
+  } else if (!exists) {
+    await ftpClient.ensureDir(remoteDir);
+  } else if (options.force) {
+    log.info(pc.yellow("Force flag used. Overwriting remote directory."));
+  }
+
+  const uploadSpinner = spin("Uploading files...");
+
+  let uploadedCount = 0;
+  let currentFile = "";
+  const totalFilesStr = inventory.length.toString();
+
+  try {
+    await ftpClient.uploadDir(localDir, remoteDir, (info) => {
+      if (info.name !== currentFile) {
+        uploadedCount++;
+        currentFile = info.name;
+        const countStr = uploadedCount
+          .toString()
+          .padStart(totalFilesStr.length, " ");
+        uploadSpinner.message(`${countStr}/${totalFilesStr} ${info.name}`);
+      }
+    });
+    uploadSpinner.stop("Upload complete");
+  } catch (err) {
+    uploadSpinner.cancel("Upload failed");
+    ftpClient.close();
+    throw err;
+  }
+
+  ftpClient.close();
+
+  log.info(`${pc.bold("Public URL:")} ${pc.cyan(publicUrl)}`);
+  outro(pc.green("Deploy complete!"));
+  return 0;
+}

package/src/commands/release-check/git.ts

@@ -0,0 +1,51 @@
+import { $ } from "zx";
+
+/**
+ * Checks if git is accessible and functional. Important on macOS where git
+ * may be paywalled by the Xcode license agreement.
+ */
+export async function isAccessible(): Promise<boolean> {
+  try {
+    await $`git --version`.quiet();
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Checks if the working directory is clean.
+ */
+export async function isClean(): Promise<boolean> {
+  const result = await $`git status --porcelain`.quiet();
+  return result.stdout.trim() === "";
+}
+
+/**
+ * Gets the current branch name.
+ */
+export async function getBranch(): Promise<string> {
+  const result = await $`git branch --show-current`.quiet();
+  return result.stdout.trim();
+}
+
+/**
+ * Checks if the current branch is behind its remote tracking branch.
+ */
+export async function isBehindRemote(): Promise<boolean> {
+  await $`git fetch`.quiet();
+  const result = await $`git rev-list --count HEAD..@{u}`.quiet();
+  return Number(result.stdout.trim()) > 0;
+}
+
+/**
+ * Checks if the current branch has a remote tracking branch.
+ */
+export async function hasRemote(): Promise<boolean> {
+  try {
+    await $`git rev-parse --abbrev-ref @{u}`.quiet();
+    return true;
+  } catch (err) {
+    return false;
+  }
+}

package/src/commands/release-check/index.ts

@@ -0,0 +1,61 @@
+import { intro, outro } from "@clack/prompts";
+import pc from "picocolors";
+import { getHeader, spin } from "../../lib/terminal.ts";
+import { FtpClient } from "../deploy/ftp.ts";
+import * as git from "./git.ts";
+
+/**
+ * Release checks that must pass before running an `aunty release`.
+ */
+export async function run(): Promise<number> {
+  intro(getHeader(pc.dim("aunty"), "release-check"));
+
+  const s = spin("Performing pre-release checks...");
+
+  // 1. Git Prerelease Checks
+
+  // 1.1 Check git accessibility.
+  if (!(await git.isAccessible())) {
+    s.cancel(
+      "Git is not accessible. Please ensure git is installed and any pending licenses (e.g. Xcode) are accepted.",
+    );
+    return 1;
+  }
+
+  // 1.2 Check for uncommitted changes
+  if (!(await git.isClean())) {
+    s.cancel("You have uncommitted changes.");
+    return 1;
+  }
+
+  // 1.3 Check branch
+  const branch = await git.getBranch();
+  if (branch !== "main") {
+    s.cancel(
+      `You are on the ${pc.bold(branch)} branch. Releases must be from ${pc.bold("main")}.`,
+    );
+    return 1;
+  }
+
+  // 1.4 Check remote sync
+  if (await git.hasRemote()) {
+    if (await git.isBehindRemote()) {
+      s.cancel("Your local branch is behind the remote.");
+      return 1;
+    }
+  }
+
+  // 2. Check for FTP credentials
+  s.message("Testing FTP connection...");
+  try {
+    const ftpClient = await new FtpClient().testConnection(5000, s);
+    ftpClient.close();
+  } catch {
+    // Spinner cancellation is handled by testConnection
+    return 1;
+  }
+
+  s.stop("Pre-release checks passed");
+  outro(pc.green("Ready for release!"));
+  return 0;
+}

package/src/lib/constants.ts

@@ -0,0 +1 @@
+export const BUILD_DIRECTORY_NAME = "dist";

package/src/lib/terminal.ts

@@ -0,0 +1,54 @@
+import { spinner } from "@clack/prompts";
+import pc from "picocolors";
+
+/** Get the ABC logo in ascii form */
+export const getLogo = () => `
+⣾${pc.dim("⢷")}⡾⢷${pc.dim("⡾")}⣷ 
+⢿⡾${pc.dim("⢷⡾")}⢷⡿ `;
+
+/** Get the ABC logo with optional text on each line */
+export const getHeader = (line1: string = "", line2: string = "") => {
+  const logoLine1 = `⣾${pc.dim("⢷")}⡾⢷${pc.dim("⡾")}⣷`;
+  const logoLine2 = `⢿⡾${pc.dim("⢷⡾")}⢷⡿`;
+
+  return [
+    "",
+    `${pc.gray("│")}  ${logoLine1} ${line1}`,
+    `${pc.gray("│")}  ${logoLine2} ${pc.bold(line2)}`,
+  ].join("\n");
+};
+
+/** Create an ABC loading spinner using clack's spinner */
+export const spin = (
+  text = "",
+  frames = [
+    "⣏⠀⠀",
+    "⡟⠀⠀",
+    "⠟⠄⠀",
+    "⠛⡄⠀",
+    "⠙⣄⠀",
+    "⠘⣤⠀",
+    "⠐⣤⠂",
+    "⠀⣤⠃",
+    "⠀⣠⠋",
+    "⠀⢠⠛",
+    "⠀⠠⠻",
+    "⠀⠀⢻",
+    "⠀⠀⣹",
+    "⠀⠀⣼",
+    "⠀⠐⣴",
+    "⠀⠘⣤",
+    "⠀⠙⣄",
+    "⠀⠛⡄",
+    "⠠⠛⠄",
+    "⢠⠛⠀",
+    "⣠⠋⠀",
+    "⣤⠃⠀",
+    "⣦⠂⠀",
+    "⣧⠀⠀",
+  ],
+) => {
+  const s = spinner({ frames });
+  s.start(text);
+  return s;
+};

package/src/lib/util.ts

@@ -0,0 +1,37 @@
+import fs from "node:fs/promises";
+import pc from "picocolors";
+
+/**
+ * Loads and parses a JSON file
+ * @param filePath The path to the file
+ */
+export async function loadJson<T = unknown>(filePath: string): Promise<T | null> {
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+/**
+ * Format bytes into a human-readable string with color coding.
+ * < 1MB = green
+ * >= 1MB = yellow (orange)
+ */
+export function formatSize(bytes: number): string {
+  const units = ["B", "KB", "MB", "GB"];
+  let unitIndex = 0;
+  let size = bytes;
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+
+  const formatted = `${size.toFixed(1)}${units[unitIndex]}`;
+
+  if (bytes >= 1024 * 1024) {
+    return pc.yellow(formatted);
+  }
+
+  return pc.green(formatted);
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "baseUrl": "./src",
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "paths": {
+      "~/*": ["./*"]
+    }
+  },
+  "include": ["src/**/*", "scripts/**/*"]
+}