readyup 0.0.0 → 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Thorsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# readyup
+
+Run pre-deployment verification checks against your environment and configuration. Define checklists in TypeScript kits, run them locally or from a remote source, and get clear pass/fail reporting with remediation hints.
+
+## Installation
+
+```bash
+pnpm add -D readyup
+```
+
+## Quick start
+
+Scaffold a starter config and kit:
+
+```bash
+rdy init
+```
+
+This creates two files:
+
+**`.config/rdy.config.ts`** — repo-level settings:
+
+```ts
+import { defineRdyConfig } from 'readyup';
+
+export default defineRdyConfig({
+  compile: {
+    srcDir: '.rdy/kits',
+    outDir: '.rdy/kits',
+  },
+});
+```
+
+**`.rdy/kits/default.ts`** — starter kit:
+
+```ts
+import { defineRdyKit } from 'readyup';
+
+export default defineRdyKit({
+  checklists: [
+    {
+      name: 'deploy',
+      checks: [
+        {
+          name: 'environment variables set',
+          check: () => Boolean(process.env['NODE_ENV']),
+          fix: 'Set NODE_ENV before deploying',
+        },
+      ],
+    },
+  ],
+});
+```
+
+Run the checks:
+
+```bash
+rdy run
+```
+
+## CLI reference
+
+```
+rdy [names...] [options]
+rdy <command> [options]
+```
+
+### Commands
+
+| Command          | Description                                      |
+| ---------------- | ------------------------------------------------ |
+| `run [names...]` | Run checklists (default)                         |
+| `compile [file]` | Bundle TypeScript kit(s) into self-contained ESM |
+| `init`           | Scaffold a starter config and kit                |
+
+### Run options
+
+| Option                          | Description                               |
+| ------------------------------- | ----------------------------------------- |
+| `--file, -f <path>`             | Path to a local kit file                  |
+| `--github, -g <org/repo[@ref]>` | Fetch kit from a GitHub repository        |
+| `--local, -l <path>`            | Load compiled kit from a local repository |
+| `--url, -u <url>`               | Fetch kit from a URL                      |
+| `--kit, -k <name>`              | Kit name (default: `"default"`)           |
+| `--json, -j`                    | Output results as JSON                    |
+| `--fail-on, -F <severity>`      | Fail on this severity or above            |
+| `--report-on, -R <severity>`    | Report this severity or above             |
+
+## Authoring API
+
+All helpers are type-safe identity functions that provide editor autocomplete without runtime overhead. Import them from `readyup`.
+
+| Helper                     | Description                          |
+| -------------------------- | ------------------------------------ |
+| `defineRdyConfig`          | Repo-level config                    |
+| `defineRdyKit`             | Kit (collection of checklists)       |
+| `defineRdyChecklist`       | Flat checklist                       |
+| `defineRdyStagedChecklist` | Staged checklist (sequential groups) |
+| `defineChecklists`         | Array of checklists                  |
+
+## Check utilities
+
+Reusable check functions for common assertions:
+
+```ts
+import { fileExists, fileContains, hasPackageJsonField } from 'readyup';
+```
+
+| Function                                    | Description                                            |
+| ------------------------------------------- | ------------------------------------------------------ |
+| `fileExists(path)`                          | File exists at path                                    |
+| `fileContains(path, pattern)`               | File matches a string or regex                         |
+| `fileDoesNotContain(path, pattern)`         | File does not match                                    |
+| `readFile(path)`                            | Read file contents (returns `undefined` if missing)    |
+| `hasPackageJsonField(field, value?)`        | package.json has a field (optionally matching a value) |
+| `hasDevDependency(name)`                    | package.json has a dev dependency                      |
+| `hasMinDevDependencyVersion(name, version)` | Dev dependency meets minimum version                   |
+| `readPackageJson()`                         | Parse package.json                                     |
+| `compareVersions(a, b)`                     | Compare semver strings                                 |
+
+## License
+
+MIT

package/bin/rdy.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+try {
+  await import('../dist/esm/bin/rdy.js');
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('rdy: build output not found — run `pnpm run build` first\n');
+  } else {
+    process.stderr.write(`rdy: failed to load: ${error.message}\n`);
+  }
+  process.exit(1);
+}

package/dist/esm/.cache

@@ -0,0 +1 @@
+904e9f3de206169e1dd9a08d2da490bb5bc2197691c2b1f6695536e33ae207d2

package/dist/esm/assertIsPreflightCollection.d.ts

@@ -0,0 +1,2 @@
+import type { PreflightCollection } from './types.ts';
+export declare function assertIsPreflightCollection(raw: unknown): asserts raw is PreflightCollection;

package/dist/esm/assertIsPreflightCollection.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+const SeveritySchema = z.enum(["error", "warn", "recommend"]);
+const FlatChecklistSchema = z.looseObject({
+  name: z.string().min(1),
+  checks: z.array(z.unknown())
+});
+const StagedChecklistSchema = z.looseObject({
+  name: z.string().min(1),
+  groups: z.array(z.unknown())
+});
+const ChecklistSchema = z.union([FlatChecklistSchema, StagedChecklistSchema]).refine((val) => !("checks" in val && "groups" in val), {
+  message: "Checklist cannot have both 'checks' and 'groups'"
+});
+const PreflightCollectionSchema = z.looseObject({
+  checklists: z.array(ChecklistSchema),
+  defaultSeverity: SeveritySchema.optional(),
+  failOn: SeveritySchema.optional(),
+  fixLocation: z.enum(["inline", "end"]).optional(),
+  reportOn: SeveritySchema.optional(),
+  suites: z.record(z.string(), z.array(z.string())).optional()
+});
+function assertIsPreflightCollection(raw) {
+  PreflightCollectionSchema.parse(raw);
+}
+export {
+  assertIsPreflightCollection
+};

package/dist/esm/assertIsRdyKit.d.ts

@@ -0,0 +1,2 @@
+import type { RdyKit } from './types.ts';
+export declare function assertIsRdyKit(raw: unknown): asserts raw is RdyKit;

package/dist/esm/assertIsRdyKit.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+const SeveritySchema = z.enum(["error", "warn", "recommend"]);
+const FlatChecklistSchema = z.looseObject({
+  name: z.string().min(1),
+  checks: z.array(z.unknown())
+});
+const StagedChecklistSchema = z.looseObject({
+  name: z.string().min(1),
+  groups: z.array(z.unknown())
+});
+const ChecklistSchema = z.union([FlatChecklistSchema, StagedChecklistSchema]).refine((val) => !("checks" in val && "groups" in val), {
+  message: "Checklist cannot have both 'checks' and 'groups'"
+});
+const RdyKitSchema = z.looseObject({
+  checklists: z.array(ChecklistSchema),
+  defaultSeverity: SeveritySchema.optional(),
+  failOn: SeveritySchema.optional(),
+  fixLocation: z.enum(["inline", "end"]).optional(),
+  reportOn: SeveritySchema.optional(),
+  suites: z.record(z.string(), z.array(z.string())).optional()
+});
+function assertIsRdyKit(raw) {
+  RdyKitSchema.parse(raw);
+}
+export {
+  assertIsRdyKit
+};

package/dist/esm/authoring.d.ts

@@ -0,0 +1,6 @@
+import type { RdyChecklist, RdyConfig, RdyKit, RdyStagedChecklist } from './types.ts';
+export declare function defineRdyConfig(config: RdyConfig): RdyConfig;
+export declare function defineRdyKit(kit: RdyKit): RdyKit;
+export declare function defineChecklists(checklists: Array<RdyChecklist | RdyStagedChecklist>): Array<RdyChecklist | RdyStagedChecklist>;
+export declare function defineRdyChecklist(checklist: RdyChecklist): RdyChecklist;
+export declare function defineRdyStagedChecklist(checklist: RdyStagedChecklist): RdyStagedChecklist;

package/dist/esm/authoring.js

@@ -0,0 +1,22 @@
+function defineRdyConfig(config) {
+  return config;
+}
+function defineRdyKit(kit) {
+  return kit;
+}
+function defineChecklists(checklists) {
+  return checklists;
+}
+function defineRdyChecklist(checklist) {
+  return checklist;
+}
+function defineRdyStagedChecklist(checklist) {
+  return checklist;
+}
+export {
+  defineChecklists,
+  defineRdyChecklist,
+  defineRdyConfig,
+  defineRdyKit,
+  defineRdyStagedChecklist
+};

package/dist/esm/bin/preflight.d.ts

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

package/dist/esm/bin/preflight.js

@@ -0,0 +1,12 @@
+import process from "node:process";
+import { routeCommand } from "./route.js";
+let exitCode;
+try {
+  exitCode = await routeCommand(process.argv.slice(2));
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`preflight: unexpected error: ${message}
+`);
+  exitCode = 1;
+}
+process.exit(exitCode);

package/dist/esm/bin/rdy.d.ts

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

package/dist/esm/bin/rdy.js

@@ -0,0 +1,12 @@
+import process from "node:process";
+import { routeCommand } from "./route.js";
+let exitCode;
+try {
+  exitCode = await routeCommand(process.argv.slice(2));
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`rdy: unexpected error: ${message}
+`);
+  exitCode = 1;
+}
+process.exit(exitCode);

package/dist/esm/bin/route.d.ts

@@ -0,0 +1 @@
+export declare function routeCommand(args: string[]): Promise<number>;

package/dist/esm/bin/route.js

@@ -0,0 +1,202 @@
+import process from "node:process";
+import { parseRunArgs, resolveKitSource, runCommand } from "../cli.js";
+import { compileCommand } from "../compile/compileCommand.js";
+import { initCommand } from "../init/initCommand.js";
+import { loadConfig } from "../loadConfig.js";
+import { parseArgs, translateParseError } from "../parseArgs.js";
+import { VERSION } from "../version.js";
+const SUBCOMMANDS = ["compile", "init"];
+const MIN_PREFIX_LENGTH = 3;
+function extractMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function showHelp() {
+  console.info(`
+Usage: rdy [names...] [options]
+       rdy <command> [options]
+
+Commands:
+  run [names...]       Run rdy checklists (default)
+  compile [file]       Bundle TypeScript kit(s) into self-contained ESM file(s)
+  init                 Scaffold a starter config and kit
+
+Run options:
+  --file, -f <path>                  Path to a local kit file
+  --github, -g <org/repo[@ref]>      Fetch kit from a GitHub repository
+  --local, -l <path>                 Load compiled kit from a local repository
+  --url, -u <url>                    Fetch kit from a URL
+  --kit, -k <name>                   Kit name (default: "default")
+  --json, -j                         Output results as JSON
+  --fail-on, -F <severity>           Fail on this severity or above (error, warn, recommend)
+  --report-on, -R <severity>         Report this severity or above (error, warn, recommend)
+
+Global options:
+  --help, -h           Show this help message
+  --version, -V        Show version number
+`);
+}
+function showRunHelp() {
+  console.info(`
+Usage: rdy run [names...] [options]
+
+Run rdy checklists. If no names are given, all checklists are run.
+
+Kit source (mutually exclusive):
+  --file, -f <path>                  Path to a local kit file
+  --github, -g <org/repo[@ref]>      Fetch kit from a GitHub repository
+  --local, -l <path>                 Load compiled kit from a local repository
+  --url, -u <url>                    Fetch kit from a URL
+
+Options:
+  --kit, -k <name>                   Kit name (default: "default")
+  --json, -j                         Output results as JSON
+  --fail-on, -F <severity>           Fail on this severity or above (error, warn, recommend)
+  --report-on, -R <severity>         Report this severity or above (error, warn, recommend)
+  --help, -h                         Show this help message
+
+--kit accepts relative paths (e.g., --kit shared/deploy).
+Defaults to .rdy/kits/default.ts when no source is given.
+`);
+}
+function showCompileHelp() {
+  console.info(`
+Usage: rdy compile [<file>] [options]
+
+Bundle TypeScript kit(s) into self-contained ESM bundle(s).
+If no file is given, all sources from the config's srcDir are compiled.
+
+Modes:
+  rdy compile                  Compile all sources from the config's srcDir
+  rdy compile <file>           Compile a single file
+
+Options:
+  --output, -o <path>  Output file path (single-file mode only)
+  --help, -h           Show this help message
+`);
+}
+function showInitHelp() {
+  console.info(`
+Usage: rdy init [options]
+
+Scaffold a starter config and kit file.
+
+Options:
+  --dry-run, -n   Preview changes without writing files
+  --force, -f     Overwrite existing files
+  --help, -h      Show this help message
+`);
+}
+function findTypoMatch(input) {
+  if (input.length < MIN_PREFIX_LENGTH || input.startsWith("-")) {
+    return void 0;
+  }
+  for (const cmd of SUBCOMMANDS) {
+    if (cmd !== input && cmd.startsWith(input)) {
+      return cmd;
+    }
+  }
+  return void 0;
+}
+async function routeCommand(args) {
+  const command = args[0];
+  if (command === void 0 || command === "--help" || command === "-h") {
+    showHelp();
+    return 0;
+  }
+  if (command === "--version" || command === "-V") {
+    console.info(VERSION);
+    return 0;
+  }
+  if (command === "run") {
+    return handleRun(args.slice(1));
+  }
+  if (command === "compile") {
+    const flags = args.slice(1);
+    if (flags.some((f) => f === "--help" || f === "-h")) {
+      showCompileHelp();
+      return 0;
+    }
+    try {
+      return await compileCommand(flags);
+    } catch (error) {
+      process.stderr.write(`Error: ${extractMessage(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "init") {
+    const flags = args.slice(1);
+    if (flags.some((f) => f === "--help" || f === "-h")) {
+      showInitHelp();
+      return 0;
+    }
+    const initFlagSchema = {
+      dryRun: { long: "--dry-run", type: "boolean", short: "-n" },
+      force: { long: "--force", type: "boolean", short: "-f" }
+    };
+    let parsed;
+    try {
+      parsed = parseArgs(flags, initFlagSchema);
+    } catch (error) {
+      process.stderr.write(`Error: ${translateParseError(error)}
+`);
+      return 1;
+    }
+    return initCommand({ dryRun: parsed.flags.dryRun, force: parsed.flags.force });
+  }
+  const typoMatch = findTypoMatch(command);
+  if (typoMatch !== void 0) {
+    process.stderr.write(`Error: Unknown command '${command}'. Did you mean 'rdy ${typoMatch}'?
+`);
+    return 1;
+  }
+  return handleRun(args);
+}
+async function handleRun(flags) {
+  if (flags.some((f) => f === "--help" || f === "-h")) {
+    showRunHelp();
+    return 0;
+  }
+  let parsed;
+  try {
+    parsed = parseRunArgs(flags);
+  } catch (error) {
+    process.stderr.write(`Error: ${extractMessage(error)}
+`);
+    return 1;
+  }
+  let config;
+  try {
+    config = await loadConfig();
+  } catch (error) {
+    process.stderr.write(`Error: ${extractMessage(error)}
+`);
+    return 1;
+  }
+  let kitSource;
+  try {
+    kitSource = resolveKitSource({
+      filePath: parsed.filePath,
+      githubValue: parsed.githubValue,
+      localValue: parsed.localValue,
+      urlValue: parsed.urlValue,
+      kitName: parsed.kitName,
+      internalDir: config.internal.dir,
+      internalExtension: config.internal.extension
+    });
+  } catch (error) {
+    process.stderr.write(`Error: ${extractMessage(error)}
+`);
+    return 1;
+  }
+  return runCommand({
+    kitSource,
+    json: parsed.json,
+    names: parsed.names,
+    ...parsed.failOn !== void 0 && { failOn: parsed.failOn },
+    ...parsed.reportOn !== void 0 && { reportOn: parsed.reportOn }
+  });
+}
+export {
+  routeCommand
+};

package/dist/esm/check-utils/filesystem.d.ts

@@ -0,0 +1,4 @@
+export declare function fileExists(relativePath: string): boolean;
+export declare function readFile(relativePath: string): string | undefined;
+export declare function fileContains(relativePath: string, pattern: RegExp): boolean;
+export declare function fileDoesNotContain(relativePath: string, pattern: RegExp): boolean;

package/dist/esm/check-utils/filesystem.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+function fileExists(relativePath) {
+  return existsSync(join(process.cwd(), relativePath));
+}
+function readFile(relativePath) {
+  const fullPath = join(process.cwd(), relativePath);
+  if (!existsSync(fullPath)) return void 0;
+  return readFileSync(fullPath, "utf8");
+}
+function fileContains(relativePath, pattern) {
+  const content = readFile(relativePath);
+  if (content === void 0) return false;
+  return pattern.test(content);
+}
+function fileDoesNotContain(relativePath, pattern) {
+  const content = readFile(relativePath);
+  if (content === void 0) return true;
+  return !pattern.test(content);
+}
+export {
+  fileContains,
+  fileDoesNotContain,
+  fileExists,
+  readFile
+};

package/dist/esm/check-utils/index.d.ts

@@ -0,0 +1,3 @@
+export { fileContains, fileDoesNotContain, fileExists, readFile } from './filesystem.ts';
+export { hasDevDependency, hasMinDevDependencyVersion, hasPackageJsonField, readPackageJson } from './package-json.ts';
+export { compareVersions } from './semver.ts';

package/dist/esm/check-utils/index.js

@@ -0,0 +1,14 @@
+import { fileContains, fileDoesNotContain, fileExists, readFile } from "./filesystem.js";
+import { hasDevDependency, hasMinDevDependencyVersion, hasPackageJsonField, readPackageJson } from "./package-json.js";
+import { compareVersions } from "./semver.js";
+export {
+  compareVersions,
+  fileContains,
+  fileDoesNotContain,
+  fileExists,
+  hasDevDependency,
+  hasMinDevDependencyVersion,
+  hasPackageJsonField,
+  readFile,
+  readPackageJson
+};

package/dist/esm/check-utils/package-json.d.ts

@@ -0,0 +1,6 @@
+export declare function readPackageJson(): Record<string, unknown> | undefined;
+export declare function hasPackageJsonField(field: string, expectedValue?: string): boolean;
+export declare function hasDevDependency(name: string): boolean;
+export declare function hasMinDevDependencyVersion(name: string, minVersion: string, options?: {
+    exempt?: (range: string) => boolean;
+}): boolean;

package/dist/esm/check-utils/package-json.js

@@ -0,0 +1,40 @@
+import { isRecord } from "../isRecord.js";
+import { readFile } from "./filesystem.js";
+import { compareVersions } from "./semver.js";
+function readPackageJson() {
+  const content = readFile("package.json");
+  if (content === void 0) return void 0;
+  const parsed = JSON.parse(content);
+  if (!isRecord(parsed)) return void 0;
+  return Object.fromEntries(Object.entries(parsed));
+}
+function hasPackageJsonField(field, expectedValue) {
+  const pkg = readPackageJson();
+  if (pkg === void 0) return false;
+  if (expectedValue !== void 0) return pkg[field] === expectedValue;
+  return field in pkg;
+}
+function hasDevDependency(name) {
+  const pkg = readPackageJson();
+  if (pkg === void 0) return false;
+  const devDeps = pkg.devDependencies;
+  return isRecord(devDeps) && name in devDeps;
+}
+function hasMinDevDependencyVersion(name, minVersion, options) {
+  const pkg = readPackageJson();
+  if (pkg === void 0) return false;
+  const devDeps = pkg.devDependencies;
+  if (!isRecord(devDeps) || !(name in devDeps)) return false;
+  const range = devDeps[name];
+  if (typeof range !== "string") return false;
+  if (options?.exempt?.(range)) return true;
+  const versionMatch = /(\d+\.\d+\.\d+)/.exec(range)?.[1];
+  if (versionMatch === void 0) return false;
+  return compareVersions(versionMatch, minVersion) >= 0;
+}
+export {
+  hasDevDependency,
+  hasMinDevDependencyVersion,
+  hasPackageJsonField,
+  readPackageJson
+};

package/dist/esm/check-utils/semver.d.ts

@@ -0,0 +1 @@
+export declare function compareVersions(a: string, b: string): number;

package/dist/esm/check-utils/semver.js

@@ -0,0 +1,12 @@
+function compareVersions(a, b) {
+  const partsA = a.split(".").map(Number);
+  const partsB = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+export {
+  compareVersions
+};

package/dist/esm/cli.d.ts

@@ -0,0 +1,36 @@
+import type { Severity } from './types.ts';
+export type KitSource = {
+    path: string;
+} | {
+    url: string;
+};
+interface ParsedRunArgs {
+    kitName: string | undefined;
+    failOn?: Severity;
+    filePath: string | undefined;
+    githubValue: string | undefined;
+    json: boolean;
+    localValue: string | undefined;
+    names: string[];
+    reportOn?: Severity;
+    urlValue: string | undefined;
+}
+export declare function parseRunArgs(flags: string[]): ParsedRunArgs;
+export declare function resolveKitSource({ filePath, githubValue, localValue, urlValue, kitName, internalDir, internalExtension, }: {
+    filePath: string | undefined;
+    githubValue: string | undefined;
+    localValue: string | undefined;
+    urlValue: string | undefined;
+    kitName: string | undefined;
+    internalDir: string;
+    internalExtension: string;
+}): KitSource;
+interface RunCommandOptions {
+    kitSource: KitSource;
+    json: boolean;
+    names: string[];
+    failOn?: Severity;
+    reportOn?: Severity;
+}
+export declare function runCommand({ names, kitSource, json, failOn, reportOn }: RunCommandOptions): Promise<number>;
+export {};