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

package/CONTRIBUTING.md

@@ -9,46 +9,43 @@ git clone git@github.com:abcnews/aunty.git
 ...then, from the project directory, run:
 
 ```bash
+npm run build
 npm link
 ```
 
-This will link the globally-available `aunty` command to your clone.
-
-To revert to your original global install, run:
+This will link the globally-available `aunty` command to your clone. While developing, run:
 
 ```bash
-npm unlink
+npm run watch
 ```
 
-## Releasing new versions of `@abcnews/aunty`
+to compile changes to the `dist/` directory automatically.
 
-Releases are managed by `release-it`. To release a new version of aunty from the default branch, run:
+To revert and uninstall the locally linked version, run:
 
-```
-npm run release
+```bash
+npm uninstall -g @abcnews/aunty
 ```
 
-By default this will do the following:
+To reinstall the latest published registry version:
 
-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
+```bash
+npm install -g @abcnews/aunty
+```
 
-If you want to cut a minor or major release, run either of the following commands instead:
+For ease of use, you can use the Aunty version directly with `node <path to aunty repo>/dist/bin/aunty.js -h`.
 
-```
-npm run release -- minor
-npm run release -- major
-```
+## Releasing new versions of `@abcnews/aunty`
 
-If you're ever unsure about what will happen, you can perform a dry run (which logs to the console) by running:
+Releases are managed by `np`. To release a new version of aunty from the default branch, run:
 
+```bash
+npm run release
 ```
-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.
+This will run tests, prompt you to select the version increment, and then publish to npm, commit, tag, and push to GitHub.
+
+For more information, see the [`np` documentation](https://github.com/sindresorhus/np).
 
 ## Style
 

package/README.md

@@ -3,3 +3,40 @@
 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).
+
+# Developing
+
+To develop on Aunty, run the watch command to compile your changes in real-time:
+
+```bash
+npm run watch
+```
+
+Or build the project manually:
+
+```bash
+npm run build
+```
+
+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.