rtfct 0.1.0

package/src/args.ts

@@ -0,0 +1,104 @@
+/**
+ * The Argument Parser — Interprets the Tech-Priest's Commands
+ *
+ * Parses CLI arguments into structured commands and flags.
+ */
+
+export type Command = "init" | "add" | "status" | "regenerate" | "praise";
+
+export interface ParsedFlags {
+  help: boolean;
+  version: boolean;
+  force: boolean;
+  yes: boolean;
+  with: string[];
+}
+
+export interface ParsedArgs {
+  command?: Command;
+  args: string[];
+  flags: ParsedFlags;
+  error?: string;
+}
+
+const VALID_COMMANDS: Command[] = [
+  "init",
+  "add",
+  "status",
+  "regenerate",
+  "praise",
+];
+
+/**
+ * Parse command line arguments into structured form.
+ * @param argv - Raw arguments (typically process.argv.slice(2))
+ */
+export const parseArgs = (argv: string[]): ParsedArgs => {
+  const flags: ParsedFlags = {
+    help: false,
+    version: false,
+    force: false,
+    yes: false,
+    with: [],
+  };
+
+  const args: string[] = [];
+  let command: Command | undefined;
+  let error: string | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    // Handle flags
+    if (arg.startsWith("--")) {
+      const flag = arg.slice(2);
+
+      if (flag === "help") {
+        flags.help = true;
+      } else if (flag === "version") {
+        flags.version = true;
+      } else if (flag === "force") {
+        flags.force = true;
+      } else if (flag === "yes") {
+        flags.yes = true;
+      } else if (flag === "with") {
+        // Next argument is the preset list
+        const nextArg = argv[++i];
+        if (nextArg) {
+          flags.with = nextArg.split(",").map((s) => s.trim());
+        }
+      } else {
+        error = `Unknown flag: --${flag}`;
+        break;
+      }
+    } else if (arg.startsWith("-")) {
+      const flag = arg.slice(1);
+
+      if (flag === "h") {
+        flags.help = true;
+      } else if (flag === "v") {
+        flags.version = true;
+      } else if (flag === "f") {
+        flags.force = true;
+      } else if (flag === "y") {
+        flags.yes = true;
+      } else {
+        error = `Unknown flag: -${flag}`;
+        break;
+      }
+    } else if (!command) {
+      // First non-flag argument is the command
+      if (VALID_COMMANDS.includes(arg as Command)) {
+        command = arg as Command;
+      } else {
+        error = `Unknown command: ${arg}`;
+        break;
+      }
+    } else {
+      // Additional arguments after command
+      args.push(arg);
+    }
+  }
+
+  return { command, args, flags, error };
+};

package/src/commands/add.ts

@@ -0,0 +1,78 @@
+/**
+ * The Add Command — Incorporate a Codex into an Existing Project
+ *
+ * Adds a preset to an already consecrated project.
+ */
+
+import { stat } from "fs/promises";
+import { join } from "path";
+import { resolvePreset, writePreset, isPresetInstalled } from "../presets";
+
+export interface AddResult {
+  success: boolean;
+  message: string;
+}
+
+/**
+ * Run the add command to incorporate a preset.
+ */
+export const runAdd = async (
+  targetDir: string,
+  presetName: string
+): Promise<AddResult> => {
+  const projectDir = join(targetDir, ".project");
+
+  // Check if .project/ exists
+  try {
+    const stats = await stat(projectDir);
+    if (!stats.isDirectory()) {
+      return {
+        success: false,
+        message:
+          "No .project/ folder found. Run 'rtfct init' first to consecrate the project.",
+      };
+    }
+  } catch {
+    return {
+      success: false,
+      message:
+        "No .project/ folder found. Run 'rtfct init' first to consecrate the project.",
+    };
+  }
+
+  // Resolve the preset
+  const result = await resolvePreset(presetName);
+  if (!result.success) {
+    return {
+      success: false,
+      message: result.error,
+    };
+  }
+
+  // Check if already installed
+  if (await isPresetInstalled(targetDir, result.preset.name)) {
+    return {
+      success: false,
+      message: `Preset '${presetName}' is already incorporated into this project.`,
+    };
+  }
+
+  // Write the preset
+  await writePreset(targetDir, result.preset);
+
+  return {
+    success: true,
+    message: `Codex '${presetName}' has been incorporated.`,
+  };
+};
+
+/**
+ * Format the add result for CLI output.
+ */
+export const formatAdd = (result: AddResult): string => {
+  if (result.success) {
+    return `✓ ${result.message}\n\nThe Omnissiah provides.`;
+  } else {
+    return `✗ ${result.message}`;
+  }
+};

package/src/commands/init.ts

@@ -0,0 +1,128 @@
+/**
+ * The Init Command — Consecrate a New Project
+ *
+ * Creates the .project/ folder structure with Sacred Texts.
+ */
+
+import { mkdir, writeFile, rm, stat } from "fs/promises";
+import { join } from "path";
+import { resolvePreset, writePreset, BASE_PRESET } from "../presets";
+
+export interface InitOptions {
+  force?: boolean;
+  presets?: string[];
+}
+
+export interface InitResult {
+  success: boolean;
+  message: string;
+  presetErrors?: string[];
+}
+
+/**
+ * Run the init command to consecrate a project.
+ */
+export const runInit = async (
+  targetDir: string,
+  options: InitOptions = {}
+): Promise<InitResult> => {
+  const projectDir = join(targetDir, ".project");
+
+  // Check if .project/ already exists
+  try {
+    const stats = await stat(projectDir);
+    if (stats.isDirectory()) {
+      if (options.force) {
+        // Purify existing .project/
+        await rm(projectDir, { recursive: true });
+      } else {
+        return {
+          success: false,
+          message:
+            "The .project/ folder already exists. Use --force to purify and recreate.",
+        };
+      }
+    }
+  } catch {
+    // Directory doesn't exist, which is what we want
+  }
+
+  // Create the directory structure
+  const directories = [
+    projectDir,
+    join(projectDir, "specs"),
+    join(projectDir, "design"),
+    join(projectDir, "adrs"),
+    join(projectDir, "kanban"),
+    join(projectDir, "testing"),
+    join(projectDir, "references"),
+    join(projectDir, "presets"),
+  ];
+
+  for (const dir of directories) {
+    await mkdir(dir, { recursive: true });
+  }
+
+  // Write the Sacred Texts from the Base Codex
+  for (const file of BASE_PRESET.files) {
+    const filePath = join(projectDir, file.path);
+    const fileDir = join(filePath, "..");
+    await mkdir(fileDir, { recursive: true });
+    await writeFile(filePath, file.content);
+  }
+
+  // Install the Base Codex as a preset (for manifest tracking)
+  await writePreset(targetDir, BASE_PRESET);
+
+  // Handle presets if specified
+  const presetErrors: string[] = [];
+  if (options.presets && options.presets.length > 0) {
+    for (const presetName of options.presets) {
+      const result = await resolvePreset(presetName);
+      if (result.success) {
+        await writePreset(targetDir, result.preset);
+      } else {
+        presetErrors.push(result.error);
+      }
+    }
+  }
+
+  if (presetErrors.length > 0) {
+    return {
+      success: true,
+      message:
+        "Project consecrated with warnings. Some presets failed to install.",
+      presetErrors,
+    };
+  }
+
+  return {
+    success: true,
+    message: "Project consecrated. The Sacred Texts have been inscribed.",
+  };
+};
+
+/**
+ * Format the init result for CLI output.
+ */
+export const formatInit = (result: InitResult): string => {
+  const lines: string[] = [];
+
+  if (result.success) {
+    lines.push("✓ " + result.message);
+    lines.push("");
+    lines.push("The Omnissiah provides.");
+  } else {
+    lines.push("✗ " + result.message);
+  }
+
+  if (result.presetErrors && result.presetErrors.length > 0) {
+    lines.push("");
+    lines.push("Preset warnings:");
+    for (const error of result.presetErrors) {
+      lines.push("  - " + error);
+    }
+  }
+
+  return lines.join("\n");
+};

package/src/commands/praise.ts

@@ -0,0 +1,19 @@
+/**
+ * The Praise Command — Recite the Sacred Litany
+ *
+ * Outputs the Litany of Deterministic Codegen.
+ */
+
+const LITANY = `The flesh is weak, but the protocol is strong.
+The code is temporary, but the spec endures.
+The tests do not lie, and the agent does not tire.
+From specification, code. From code, verification. From verification, truth.
+The Omnissiah provides.
+Praise the Machine Spirit.`;
+
+/**
+ * Run the praise command.
+ */
+export const runPraise = (): string => {
+  return LITANY;
+};

package/src/commands/regenerate.ts

@@ -0,0 +1,122 @@
+/**
+ * The Regenerate Command — Purify the Codebase
+ *
+ * Deletes generated paths in preparation for regeneration.
+ */
+
+import { rm, stat } from "fs/promises";
+import { join } from "path";
+import { collectGeneratedPaths } from "../manifest";
+
+export interface RegenerateOptions {
+  yes?: boolean;
+}
+
+export interface RegenerateResult {
+  success: boolean;
+  message: string;
+  deletedPaths?: string[];
+  requiresConfirmation?: boolean;
+  pathsToDelete?: string[];
+}
+
+/**
+ * Run the regenerate command to purify the codebase.
+ */
+export const runRegenerate = async (
+  targetDir: string,
+  options: RegenerateOptions = {}
+): Promise<RegenerateResult> => {
+  const projectDir = join(targetDir, ".project");
+
+  // Check if .project/ exists
+  try {
+    const stats = await stat(projectDir);
+    if (!stats.isDirectory()) {
+      return {
+        success: false,
+        message:
+          "No .project/ folder found. Run 'rtfct init' first to consecrate the project.",
+      };
+    }
+  } catch {
+    return {
+      success: false,
+      message:
+        "No .project/ folder found. Run 'rtfct init' first to consecrate the project.",
+    };
+  }
+
+  // Collect paths to delete
+  const pathsToDelete = await collectGeneratedPaths(targetDir);
+
+  // If not confirmed, request confirmation
+  if (!options.yes) {
+    return {
+      success: true,
+      requiresConfirmation: true,
+      pathsToDelete,
+      message: "Confirmation required",
+    };
+  }
+
+  // Delete the paths
+  const deletedPaths: string[] = [];
+  for (const path of pathsToDelete) {
+    const fullPath = join(targetDir, path);
+    try {
+      await rm(fullPath, { recursive: true });
+      deletedPaths.push(path);
+    } catch {
+      // Path doesn't exist, which is fine
+    }
+  }
+
+  return {
+    success: true,
+    message: "The codebase has been purified.",
+    deletedPaths,
+  };
+};
+
+/**
+ * Format the regenerate result for CLI output.
+ */
+export const formatRegenerate = (result: RegenerateResult): string => {
+  if (!result.success) {
+    return `✗ ${result.message}`;
+  }
+
+  if (result.requiresConfirmation) {
+    const lines: string[] = [];
+    lines.push("⚠ The Rite of Purification");
+    lines.push("");
+    lines.push("The following paths will be purified:");
+    for (const path of result.pathsToDelete || []) {
+      lines.push(`  - ${path}`);
+    }
+    lines.push("");
+    lines.push("Run with --yes to confirm.");
+    return lines.join("\n");
+  }
+
+  const lines: string[] = [];
+  lines.push("✓ " + result.message);
+  lines.push("");
+
+  if (result.deletedPaths && result.deletedPaths.length > 0) {
+    lines.push("Purified paths:");
+    for (const path of result.deletedPaths) {
+      lines.push(`  - ${path}`);
+    }
+  } else {
+    lines.push("No paths were purified (already clean).");
+  }
+
+  lines.push("");
+  lines.push("Invoke the Machine Spirit to regenerate.");
+  lines.push("");
+  lines.push("The Omnissiah provides.");
+
+  return lines.join("\n");
+};

package/src/commands/status.ts

@@ -0,0 +1,163 @@
+/**
+ * The Status Command — Reveal the State of the Litany of Tasks
+ *
+ * Parses kanban markdown and displays project status.
+ */
+
+import { readFile, stat } from "fs/promises";
+import { join } from "path";
+import { parseKanbanFile, formatRelativeTime, type Task } from "../kanban";
+
+export interface StatusResult {
+  success: boolean;
+  message?: string;
+  data?: {
+    projectName: string;
+    backlogCount: number;
+    inProgressCount: number;
+    doneCount: number;
+    currentTask: Task | null;
+    lastActivity: Date | null;
+  };
+}
+
+/**
+ * Helper to check if date a is newer than date b.
+ */
+const isNewer = (a: Date, b: Date | null): boolean => {
+  if (b === null) return true;
+  return a.getTime() > b.getTime();
+};
+
+/**
+ * Run the status command to display project state.
+ */
+export const runStatus = async (targetDir: string): Promise<StatusResult> => {
+  const projectDir = join(targetDir, ".project");
+  const kanbanDir = join(projectDir, "kanban");
+
+  // Check if .project/ exists
+  try {
+    const stats = await stat(projectDir);
+    if (!stats.isDirectory()) {
+      return {
+        success: false,
+        message:
+          "No .project/ folder found. Run 'rtfct init' first to consecrate the project.",
+      };
+    }
+  } catch {
+    return {
+      success: false,
+      message:
+        "No .project/ folder found. Run 'rtfct init' first to consecrate the project.",
+    };
+  }
+
+  // Get project name from directory
+  const projectName = targetDir.split("/").pop() || "unknown";
+
+  // Parse kanban files
+  let backlogCount = 0;
+  let inProgressCount = 0;
+  let doneCount = 0;
+  let currentTask: Task | null = null;
+  let lastActivity: Date | null = null;
+
+  try {
+    const backlogPath = join(kanbanDir, "backlog.md");
+    const backlogContent = await readFile(backlogPath, "utf-8");
+    const backlogStats = await stat(backlogPath);
+    const backlogResult = parseKanbanFile(backlogContent, "backlog");
+    backlogCount = backlogResult.count;
+    if (isNewer(backlogStats.mtime, lastActivity)) {
+      lastActivity = backlogStats.mtime;
+    }
+  } catch {
+    // File doesn't exist or isn't readable
+  }
+
+  try {
+    const inProgressPath = join(kanbanDir, "in-progress.md");
+    const inProgressContent = await readFile(inProgressPath, "utf-8");
+    const inProgressStats = await stat(inProgressPath);
+    const inProgressResult = parseKanbanFile(inProgressContent, "in-progress");
+    inProgressCount = inProgressResult.count;
+    currentTask = inProgressResult.currentTask;
+    if (isNewer(inProgressStats.mtime, lastActivity)) {
+      lastActivity = inProgressStats.mtime;
+    }
+  } catch {
+    // File doesn't exist or isn't readable
+  }
+
+  try {
+    const donePath = join(kanbanDir, "done.md");
+    const doneContent = await readFile(donePath, "utf-8");
+    const doneStats = await stat(donePath);
+    const doneResult = parseKanbanFile(doneContent, "done");
+    doneCount = doneResult.count;
+    if (isNewer(doneStats.mtime, lastActivity)) {
+      lastActivity = doneStats.mtime;
+    }
+  } catch {
+    // File doesn't exist or isn't readable
+  }
+
+  return {
+    success: true,
+    data: {
+      projectName,
+      backlogCount,
+      inProgressCount,
+      doneCount,
+      currentTask,
+      lastActivity,
+    },
+  };
+};
+
+/**
+ * Format the status result for CLI output.
+ */
+export const formatStatus = (result: StatusResult): string => {
+  if (!result.success) {
+    return `✗ ${result.message}`;
+  }
+
+  const data = result.data!;
+  const lines: string[] = [];
+
+  lines.push(`rtfct: ${data.projectName}`);
+  lines.push("");
+  lines.push("══════════════════════════════════");
+  lines.push("  The Litany of Tasks");
+  lines.push("══════════════════════════════════");
+  lines.push(
+    `  Backlog:      ${data.backlogCount} unordained task${data.backlogCount === 1 ? "" : "s"}`
+  );
+  lines.push(
+    `  In Progress:  ${data.inProgressCount} ordained task${data.inProgressCount === 1 ? "" : "s"}`
+  );
+
+  if (data.currentTask) {
+    lines.push(`    → [${data.currentTask.id}] ${data.currentTask.title}`);
+  }
+
+  lines.push(
+    `  Completed:    ${data.doneCount} work${data.doneCount === 1 ? "" : "s"} done`
+  );
+  lines.push("══════════════════════════════════");
+  lines.push("");
+
+  if (data.lastActivity) {
+    lines.push(`Last activity: ${formatRelativeTime(data.lastActivity)}`);
+  } else {
+    lines.push("Last activity: unknown");
+  }
+
+  lines.push("");
+  lines.push("The Omnissiah provides.");
+
+  return lines.join("\n");
+};

package/src/help.ts

@@ -0,0 +1,52 @@
+/**
+ * The Help System — Guidance for the Tech-Priest
+ *
+ * Displays usage information, version, and error messages.
+ */
+
+const VERSION = "0.1.0";
+
+const USAGE = `
+rtfct — The Ritual Factory
+
+USAGE:
+  rtfct <command> [options]
+
+COMMANDS:
+  init          Consecrate a new project with Sacred Texts
+  add <preset>  Incorporate a Codex into an existing project
+  status        Reveal the state of the Litany of Tasks
+  regenerate    Purify the codebase for regeneration
+  praise        Recite the Litany of Deterministic Codegen
+
+OPTIONS:
+  --help, -h     Display this sacred guidance
+  --version, -v  Display the version of rtfct
+  --force, -f    Purify existing .project/ and recreate (init only)
+  --yes, -y      Skip confirmation prompts
+  --with <list>  Comma-separated Codices to include (init only)
+
+EXAMPLES:
+  rtfct init                    # Basic consecration
+  rtfct init --with zig         # Consecrate with Zig Codex
+  rtfct init --with zig,elixir  # Multiple Codices
+  rtfct add typescript          # Add TypeScript Codex
+  rtfct status                  # View task progress
+  rtfct regenerate --yes        # Purify without confirmation
+
+The Omnissiah provides.
+`.trim();
+
+export const printHelp = (): void => {
+  console.log(USAGE);
+};
+
+export const printVersion = (): void => {
+  console.log(`rtfct v${VERSION}`);
+};
+
+export const printError = (message: string): void => {
+  console.error(`Error: ${message}`);
+  console.error("");
+  console.error("Run 'rtfct --help' for usage.");
+};