legacymaxxing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openclaw
+
+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,62 @@
+# legacymaxxing
+
+**A loop CLI that guides an AI agent through the code-modernization lifecycle.**
+
+Instead of a human typing modernization commands at an agent one phase at a time,
+legacymaxxing inverts the control: a deterministic, gated state-machine drives the
+agent. It emits the next phase's prompt, runs the agent (Codex first) against a
+legacy system, validates the artifacts the agent wrote, records the result, and
+advances — pausing only at the human approval gate.
+
+> **Status: early (v0.1).** Codex is the only real provider wired up; a Claude
+> provider is planned via the same adapter. There is **no auto-commit / auto-PR**:
+> legacymaxxing writes files and state, you land them. The `codex` provider path is
+> not yet exercised in CI — the `mock` provider covers the pipeline. Treat the
+> exact `codex exec` flags as needing a tune against your installed version.
+
+It is the [`code-modernization` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-modernization)
+turned inside-out: the same `assess → map → extract → brief → transform/reimagine
+→ harden` lifecycle, but as a resumable CLI an agent can be looped against.
+
+## The lifecycle
+
+```
+assess ─▶ map ─────▶ brief ──[human gate]──▶ transform ─┐  (mutating, --apply)
+   └────▶ extract ──▶          │                          ├─▶ modernized/
+                               └────────────────────────▶ reimagine (mutating)
+assess ─▶ harden ─▶ security_remediation.patch  (generated, never applied)
+```
+
+- **assess / map / extract / brief** are read-only: the agent writes analysis docs
+  into `analysis/<system>/`. `brief` produces a plan and then **waits for you**.
+- **transform / reimagine** are mutating: they write new code into
+  `modernized/<system>/` and require an approved brief, an explicit `--apply`, and
+  a clean git worktree.
+- **harden** scans the legacy system and produces a reviewable patch — it is never
+  applied, and `legacy/` is never edited.
+
+## Quickstart
+
+```bash
+legacymaxxing init --system billing --legacy legacy/billing   # register + write state
+legacymaxxing loop                                            # run discovery, stop at brief gate
+legacymaxxing report                                          # see what was produced
+legacymaxxing gate brief --approve                            # human approves the plan
+legacymaxxing run transform --module interest-calc --apply    # one strangler-fig rewrite
+```
+
+Want to drive the agent yourself? `legacymaxxing next` prints the exact prompt for
+the next runnable phase (no model call) so you can paste it into any agent.
+
+## CLI contract
+
+- `stdout` is the result (`--json` for the stable machine shape; markdown body
+  otherwise); `stderr` is progress/diagnostics. `--quiet` mutes stderr.
+- **Exit codes:** `0` ok · `1` runtime · `2` invalid usage · `3` dirty worktree ·
+  `4` provider auth · `5` provider quota · `6` validation/gate failed ·
+  `7` lock conflict / external-CLI failure · `8` malformed model output.
+- State lives in `.legacymaxxing/` (runtime subdirs gitignored). Every run, phase,
+  and gate decision is a JSON record; reruns are deterministic and resumable.
+
+See [`SPEC.md`](SPEC.md) for the full contract and [`AGENTS.md`](AGENTS.md) for
+contributor guidelines. MIT licensed.

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { type Flags } from "./context.js";
+type ParsedArgs = {
+    command: string;
+    positionals: string[];
+    flags: Flags;
+};
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function validateCommandFlags(command: string, flags: Flags): void;
+export declare function main(argv: string[]): Promise<void>;
+export {};

package/dist/cli.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ToolError } from "./errors.js";
+import { makeContext, resolveGlobalOptions } from "./context.js";
+import { cleanLocksCommand, doctorCommand, gateCommand, initCommand, loopCommand, nextCommand, reportCommand, revalidateCommand, runCommand, statusCommand, } from "./commands.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+// Per-command flag whitelist (global flags are allowed everywhere). Validated
+// BEFORE any side effect; an unknown flag is exit 2, never silently ignored.
+const commandFlags = {
+    init: new Set(["system", "legacy", "force"]),
+    status: new Set([]),
+    next: new Set(["module", "vision"]),
+    run: new Set(["phase", "module", "vision", "apply", "yes"]),
+    loop: new Set(["until"]),
+    gate: new Set(["phase", "approve", "reject", "note"]),
+    report: new Set([]),
+    revalidate: new Set(["phase"]),
+    doctor: new Set([]),
+    "clean-locks": new Set([]),
+};
+const globalFlags = new Set([
+    "root",
+    "stateDir",
+    "config",
+    "system",
+    "provider",
+    "model",
+    "json",
+    "plain",
+    "quiet",
+    "verbose",
+    "debug",
+    "noColor",
+    "noInput",
+]);
+const booleanFlags = new Set([
+    "force",
+    "apply",
+    "yes",
+    "approve",
+    "reject",
+    "json",
+    "plain",
+    "quiet",
+    "verbose",
+    "debug",
+    "noColor",
+    "noInput",
+    "help",
+    "version",
+]);
+const shortFlags = {
+    q: "quiet",
+    v: "verbose",
+    h: "help",
+};
+function camel(value) {
+    return value.replace(/-([a-z])/gu, (_, char) => char.toUpperCase());
+}
+function dash(value) {
+    return value.replace(/[A-Z]/gu, (char) => `-${char.toLowerCase()}`);
+}
+export function parseArgs(argv) {
+    const flags = {};
+    const positionals = [];
+    let command = "";
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === undefined)
+            break;
+        if (token.startsWith("--")) {
+            const body = token.slice(2);
+            const eq = body.indexOf("=");
+            if (eq !== -1) {
+                flags[camel(body.slice(0, eq))] = body.slice(eq + 1);
+                continue;
+            }
+            const key = camel(body);
+            if (booleanFlags.has(key)) {
+                flags[key] = true;
+                continue;
+            }
+            const next = argv[index + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                flags[key] = next;
+                index += 1;
+            }
+            else {
+                flags[key] = true;
+            }
+            continue;
+        }
+        if (token.startsWith("-") && token.length > 1) {
+            for (const char of token.slice(1))
+                flags[shortFlags[char] ?? char] = true;
+            continue;
+        }
+        if (!command)
+            command = token;
+        else
+            positionals.push(token);
+    }
+    return { command, positionals, flags };
+}
+export function validateCommandFlags(command, flags) {
+    const allowed = commandFlags[command];
+    if (!allowed)
+        throw new ToolError(`unknown command: ${command}`, 2, "invalid-usage");
+    for (const key of Object.keys(flags)) {
+        if (globalFlags.has(key) || allowed.has(key))
+            continue;
+        throw new ToolError(`unknown flag for ${command}: --${dash(key)}`, 2, "invalid-usage");
+    }
+}
+async function dispatch(ctx, command, flags) {
+    switch (command) {
+        case "init":
+            return initCommand(ctx, flags);
+        case "status":
+            return statusCommand(ctx, flags);
+        case "next":
+            return nextCommand(ctx, flags);
+        case "run":
+            return runCommand(ctx, flags);
+        case "loop":
+            return loopCommand(ctx, flags);
+        case "gate":
+            return gateCommand(ctx, flags);
+        case "report":
+            return reportCommand(ctx, flags);
+        case "revalidate":
+            return revalidateCommand(ctx, flags);
+        case "doctor":
+            return doctorCommand(ctx, flags);
+        case "clean-locks":
+            return cleanLocksCommand(ctx, flags);
+        default:
+            throw new ToolError(`unknown command: ${command}`, 2, "invalid-usage");
+    }
+}
+// The ONLY function that writes results to stdout.
+function writeResult(result, json, plain) {
+    if (json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    if (result && typeof result === "object" && "markdown" in result && !plain) {
+        process.stdout.write(String(result.markdown));
+        return;
+    }
+    if (result && typeof result === "object") {
+        for (const [key, value] of Object.entries(result)) {
+            if (value === null || typeof value === "object")
+                continue;
+            process.stdout.write(`${key}: ${String(value)}\n`);
+        }
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function helpText() {
+    return [
+        `legacymaxxing ${pkg.version} — guide an agent through the code-modernization lifecycle`,
+        "",
+        "Usage: legacymaxxing <command> [flags]",
+        "",
+        "Commands:",
+        "  init --system <name> --legacy <path>   register a legacy system + write state",
+        "  status                                 phase table for a system",
+        "  next                                   print the next runnable phase's prompt (no model call)",
+        "  run <phase> [--module m] [--apply]     run one phase via the provider",
+        "  loop [--until <phase>]                 run read-only phases until a gate blocks",
+        "  gate <phase> --approve|--reject        record a human gate decision",
+        "  report                                 markdown summary of all phases",
+        "  revalidate <phase>                     re-check a phase's artifacts on disk",
+        "  doctor                                 check provider + optional tools + state",
+        "  clean-locks                            remove lock files",
+        "",
+        `Phases: assess → map → extract → brief [gate] → transform/reimagine → harden`,
+        "",
+        "Global flags: --root --state-dir --config --system --provider --model",
+        "              --json --plain -q/--quiet -v/--verbose --debug --no-color --no-input",
+        "",
+    ].join("\n");
+}
+export async function main(argv) {
+    if (argv.includes("--version")) {
+        process.stdout.write(`${pkg.version}\n`);
+        return;
+    }
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(helpText());
+        return;
+    }
+    const { command, positionals, flags } = parseArgs(argv);
+    if (!command) {
+        process.stdout.write(helpText());
+        return;
+    }
+    if ((command === "run" || command === "gate" || command === "revalidate") &&
+        positionals[0] !== undefined &&
+        flags["phase"] === undefined) {
+        flags["phase"] = positionals[0];
+    }
+    validateCommandFlags(command, flags);
+    const options = resolveGlobalOptions(flags, process.env);
+    const ctx = makeContext(options);
+    const result = await dispatch(ctx, command, flags);
+    writeResult(result, options.json, options.plain);
+    if (command === "doctor" && isRecord(result) && result["ready"] === false) {
+        process.exitCode = 2;
+    }
+}
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    main(process.argv.slice(2)).catch((error) => {
+        if (error instanceof ToolError) {
+            process.stderr.write(`error: ${error.message}\n`);
+            process.exitCode = error.exitCode;
+            return;
+        }
+        process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/commands.d.ts

@@ -0,0 +1,11 @@
+import type { Context, Flags } from "./context.js";
+export declare function initCommand(ctx: Context, flags: Flags): Promise<unknown>;
+export declare function statusCommand(ctx: Context, flags: Flags): Promise<unknown>;
+export declare function nextCommand(ctx: Context, flags: Flags): Promise<unknown>;
+export declare function runCommand(ctx: Context, flags: Flags): Promise<unknown>;
+export declare function loopCommand(ctx: Context, flags: Flags): Promise<unknown>;
+export declare function gateCommand(ctx: Context, flags: Flags): Promise<unknown>;
+export declare function reportCommand(ctx: Context, flags: Flags): Promise<unknown>;
+export declare function revalidateCommand(ctx: Context, flags: Flags): Promise<unknown>;
+export declare function doctorCommand(ctx: Context, _flags: Flags): Promise<unknown>;
+export declare function cleanLocksCommand(ctx: Context, _flags: Flags): Promise<unknown>;