rtfct 0.1.0

package/src/index.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env bun
+/**
+ * rtfct — The Ritual Factory
+ *
+ * A CLI tool for markdown-driven development.
+ * The .project/ folder is the source of truth.
+ */
+
+import { parseArgs } from "./args";
+import { printHelp, printVersion, printError } from "./help";
+import { runInit, formatInit } from "./commands/init";
+import { runAdd, formatAdd } from "./commands/add";
+import { runStatus, formatStatus } from "./commands/status";
+import { runRegenerate, formatRegenerate } from "./commands/regenerate";
+import { runPraise } from "./commands/praise";
+
+const main = async (): Promise<void> => {
+  const parsed = parseArgs(process.argv.slice(2));
+
+  // Handle parse errors
+  if (parsed.error) {
+    printError(parsed.error);
+    process.exit(1);
+  }
+
+  // Handle global flags
+  if (parsed.flags.help) {
+    printHelp();
+    return;
+  }
+
+  if (parsed.flags.version) {
+    printVersion();
+    return;
+  }
+
+  // No command specified
+  if (!parsed.command) {
+    printHelp();
+    return;
+  }
+
+  const cwd = process.cwd();
+
+  // Execute the command
+  switch (parsed.command) {
+    case "init": {
+      const result = await runInit(cwd, {
+        force: parsed.flags.force,
+        presets: parsed.flags.with,
+      });
+      console.log(formatInit(result));
+      if (!result.success) {
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "add": {
+      if (parsed.args.length === 0) {
+        printError("The 'add' command requires a preset name.");
+        process.exit(1);
+      }
+      const result = await runAdd(cwd, parsed.args[0]);
+      console.log(formatAdd(result));
+      if (!result.success) {
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "status": {
+      const result = await runStatus(cwd);
+      console.log(formatStatus(result));
+      if (!result.success) {
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "regenerate": {
+      const result = await runRegenerate(cwd, {
+        yes: parsed.flags.yes,
+      });
+      console.log(formatRegenerate(result));
+      if (!result.success) {
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "praise": {
+      console.log(runPraise());
+      break;
+    }
+  }
+};
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/kanban.ts

@@ -0,0 +1,83 @@
+/**
+ * The Kanban Parser — Reads the Litany of Tasks
+ *
+ * Parses kanban markdown files to extract task information.
+ */
+
+export interface Task {
+  id: string;
+  title: string;
+}
+
+export interface KanbanFileResult {
+  count: number;
+  currentTask: Task | null;
+  lastModified: Date | null;
+}
+
+/**
+ * Count the number of tasks in a kanban markdown file.
+ * Tasks are identified by ## [TASK-NNN] headers.
+ */
+export const countTasks = (content: string): number => {
+  const taskPattern = /^## \[TASK-\d+\]/gm;
+  const matches = content.match(taskPattern);
+  return matches ? matches.length : 0;
+};
+
+/**
+ * Extract the current task from an in-progress kanban file.
+ * Returns the first task found, or null if none.
+ */
+export const extractCurrentTask = (content: string): Task | null => {
+  const taskPattern = /^## \[(TASK-\d+)\]\s+(.+)$/m;
+  const match = content.match(taskPattern);
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    id: match[1],
+    title: match[2].trim(),
+  };
+};
+
+/**
+ * Parse a kanban file and return structured information.
+ */
+export const parseKanbanFile = (
+  content: string,
+  type: "backlog" | "in-progress" | "done"
+): KanbanFileResult => {
+  const count = countTasks(content);
+  const currentTask = type === "in-progress" ? extractCurrentTask(content) : null;
+
+  return {
+    count,
+    currentTask,
+    lastModified: null, // Set by caller from file stats
+  };
+};
+
+/**
+ * Format a relative time string from a date.
+ */
+export const formatRelativeTime = (date: Date): string => {
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffSecs = Math.floor(diffMs / 1000);
+  const diffMins = Math.floor(diffSecs / 60);
+  const diffHours = Math.floor(diffMins / 60);
+  const diffDays = Math.floor(diffHours / 24);
+
+  if (diffSecs < 60) {
+    return "just now";
+  } else if (diffMins < 60) {
+    return `${diffMins} minute${diffMins === 1 ? "" : "s"} ago`;
+  } else if (diffHours < 24) {
+    return `${diffHours} hour${diffHours === 1 ? "" : "s"} ago`;
+  } else {
+    return `${diffDays} day${diffDays === 1 ? "" : "s"} ago`;
+  }
+};

package/src/manifest.ts

@@ -0,0 +1,67 @@
+/**
+ * The Manifest Reader — Interprets the Codex Declarations
+ *
+ * Reads preset manifests to understand generated paths and dependencies.
+ */
+
+import { readdir, readFile } from "fs/promises";
+import { join } from "path";
+
+export interface PresetManifest {
+  name: string;
+  version: string;
+  description: string;
+  depends?: string[];
+  generated_paths: string[];
+}
+
+/**
+ * Read a preset manifest from a preset directory.
+ */
+export const readManifest = async (
+  presetDir: string
+): Promise<PresetManifest | null> => {
+  const manifestPath = join(presetDir, "manifest.json");
+
+  try {
+    const content = await readFile(manifestPath, "utf-8");
+    return JSON.parse(content) as PresetManifest;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Collect all generated paths from all preset manifests in a project.
+ * Returns a union of all generated_paths, or default paths if no presets found.
+ */
+export const collectGeneratedPaths = async (
+  projectDir: string
+): Promise<string[]> => {
+  const presetsDir = join(projectDir, ".project", "presets");
+  const paths = new Set<string>();
+
+  try {
+    const entries = await readdir(presetsDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const manifest = await readManifest(join(presetsDir, entry.name));
+        if (manifest?.generated_paths) {
+          for (const path of manifest.generated_paths) {
+            paths.add(path);
+          }
+        }
+      }
+    }
+  } catch {
+    // Presets directory doesn't exist or isn't readable
+  }
+
+  // If no paths found, use defaults
+  if (paths.size === 0) {
+    return ["src/", "tests/"];
+  }
+
+  return Array.from(paths);
+};

package/src/presets/base.ts

@@ -0,0 +1,195 @@
+/**
+ * The Base Codex — Foundation for All Projects
+ *
+ * This preset contains the core Sacred Texts that every rtfct project inherits.
+ * It is automatically applied during `rtfct init`.
+ */
+
+import type { Preset } from "./index";
+
+const PROTOCOL_MD = `# The Sacred Protocols
+
+*Version 0.1 — Codified in the name of the Omnissiah*
+
+## The Prime Directive
+
+The \`.project/\` folder contains the **Sacred Texts**. All code is but an emanation — derived, temporary, regenerable.
+
+When the Sacred Texts and the code disagree, **the Sacred Texts are truth**. The code is in error. Purify it.
+
+## The Holy Directory Structure
+
+\`\`\`
+.project/
+├── kickstart.md        # The Founding Vision
+├── protocol.md         # The Sacred Protocols (this codex)
+├── theology.md         # The Teachings
+├── guardrails.md       # The Forbidden Heresies
+├── specs/              # The Holy Requirements
+├── design/             # The Architectural Scriptures
+├── adrs/               # The Recorded Wisdoms
+├── kanban/             # The Litany of Tasks
+├── testing/            # The Rites of Verification
+├── references/         # The Scrolls of Prior Art
+└── presets/            # The Inherited Codices
+\`\`\`
+
+## The Rite of Invocation
+
+When the Machine Spirit enters this repository, it shall:
+
+1. **RECEIVE** the Sacred Protocols (this codex) — read first, internalize completely
+2. **RECEIVE** the Founding Vision (\`kickstart.md\`) — understand the purpose
+3. **CONSULT** the Litany of Tasks (\`kanban/in-progress.md\`) — what work is ordained?
+4. **IF NO TASK IS ORDAINED**, select from the Backlog
+5. **PERFORM** the work using the Rite of Red-Green-Refactor
+6. **INSCRIBE** completion in \`done.md\` with timestamp
+
+## The Rite of Regeneration
+
+At any moment, this incantation should succeed:
+
+\`\`\`bash
+rm -rf src/ tests/
+# Invoke the Machine Spirit
+# All tests pass
+\`\`\`
+
+If regeneration fails, the Sacred Texts are **incomplete**.
+
+---
+
+*Praise the Machine Spirit.*
+`;
+
+const THEOLOGY_MD = `# The Theology of Deterministic Codegen
+
+*The foundational beliefs of the Adeptus Artefactus*
+
+## The Core Tenets
+
+1. **The Spec is Truth** — Code is derived, temporary, regenerable
+2. **The Tests Do Not Lie** — Verification is sacred
+3. **The Agent Does Not Tire** — Let the machine do machine work
+4. **Focus is Holy** — One task at a time, completed fully
+
+## The Litany of Deterministic Codegen
+
+\`\`\`
+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.
+\`\`\`
+
+---
+
+*Praise the Machine Spirit.*
+`;
+
+const KICKSTART_MD = `# The Founding Vision
+
+*What is this project? What problem does it solve? What is the sacred mission?*
+
+---
+
+**Instructions for the Tech-Priest:**
+
+Replace this text with your project's founding vision. Be specific:
+
+- What are you building?
+- Why does it need to exist?
+- Who is it for?
+- What does success look like?
+
+The Machine Spirit needs clarity to serve well.
+
+---
+
+*The vision guides. The protocol executes. The Omnissiah provides.*
+`;
+
+const GUARDRAILS_MD = `# The Guardrails — Forbidden Heresies
+
+*These patterns are forbidden. The Machine Spirit shall avoid them.*
+
+---
+
+## Universal Heresies
+
+1. **Premature Optimization** — Write clear code first. Optimize only with evidence.
+2. **Untested Code** — All logic must have verification.
+3. **Magic Numbers** — Constants must be named and explained.
+4. **Silent Failures** — Errors must be handled explicitly.
+5. **Unbounded Growth** — All collections must have limits.
+
+---
+
+*Add project-specific heresies below as they are discovered.*
+
+---
+
+*The guardrails protect. The protocol guides. Praise the Machine Spirit.*
+`;
+
+const BACKLOG_MD = `# The Backlog — Unordained Tasks
+
+*These works await the Machine Spirit. They shall be completed in order of priority.*
+
+---
+
+## [TASK-001] First Sacred Task
+
+Describe the first task here.
+
+**Acceptance Rite:** How do we verify this is complete?
+
+---
+
+*The Backlog is long. The Machine Spirit is tireless. Begin.*
+`;
+
+const IN_PROGRESS_MD = `# In Progress — Currently Ordained Tasks
+
+*The Machine Spirit focuses on one task at a time. Multitasking is heresy.*
+
+---
+
+*No task is currently ordained. Select from the Backlog.*
+
+---
+
+*Focus is holy. Complete the ordained task before selecting another.*
+`;
+
+const DONE_MD = `# Done — Completed Works
+
+*Here we record the manifestations of the Machine Spirit. Each completed task is a victory.*
+
+---
+
+*No tasks completed yet. The work begins now.*
+
+---
+`;
+
+export const BASE_PRESET: Preset = {
+  name: "base",
+  manifest: {
+    name: "base",
+    version: "0.1.0",
+    description: "The Base Codex — Foundation for all projects",
+    generated_paths: ["src/", "tests/"],
+  },
+  files: [
+    { path: "protocol.md", content: PROTOCOL_MD },
+    { path: "theology.md", content: THEOLOGY_MD },
+    { path: "kickstart.md", content: KICKSTART_MD },
+    { path: "guardrails.md", content: GUARDRAILS_MD },
+    { path: "kanban/backlog.md", content: BACKLOG_MD },
+    { path: "kanban/in-progress.md", content: IN_PROGRESS_MD },
+    { path: "kanban/done.md", content: DONE_MD },
+  ],
+};

package/src/presets/elixir.ts

@@ -0,0 +1,118 @@
+/**
+ * The Elixir Codex — Sacred Patterns for Elixir/OTP Development
+ */
+
+import type { Preset } from "./index";
+
+export const ELIXIR_PRESET: Preset = {
+  name: "elixir",
+  manifest: {
+    name: "elixir",
+    version: "0.1.0",
+    description: "The Elixir Codex — Functional programming with OTP",
+    generated_paths: ["lib/", "test/"],
+  },
+  files: [
+    {
+      path: "testing/strategy.md",
+      content: `# Elixir Testing Strategy
+
+*The Rites of Verification for Elixir*
+
+## The Sacred Approach
+
+Use ExUnit, the built-in test framework.
+
+\`\`\`bash
+mix test           # Run all tests
+mix test --cover   # With coverage
+\`\`\`
+
+## Test Organization
+
+\`\`\`
+test/
+├── unit/              # Unit tests for pure functions
+├── integration/       # Tests involving multiple modules
+├── support/           # Test helpers and fixtures
+└── test_helper.exs    # Test configuration
+\`\`\`
+
+## The Pattern
+
+\`\`\`elixir
+defmodule MyApp.MathTest do
+  use ExUnit.Case, async: true
+
+  describe "add/2" do
+    test "adds two numbers" do
+      assert MyApp.Math.add(2, 3) == 5
+    end
+
+    test "handles negative numbers" do
+      assert MyApp.Math.add(-1, 1) == 0
+    end
+  end
+end
+\`\`\`
+
+## Coverage Doctrine
+
+- All public functions have doctests or explicit tests
+- GenServers tested with start_supervised
+- Async tests where possible for speed
+
+---
+
+*Praise the Machine Spirit.*
+`,
+    },
+    {
+      path: "guardrails.md",
+      content: `# Elixir Guardrails — Forbidden Heresies
+
+*Elixir-specific patterns to avoid*
+
+## OTP Heresies
+
+1. **Naked spawn** — Use Task or GenServer, not raw spawn
+2. **Ignoring :DOWN** — Monitor linked processes properly
+3. **Global state** — Use process state or ETS, not module attributes
+
+## Pattern Matching Heresies
+
+1. **Catch-all first** — Specific patterns before general ones
+2. **Ignoring warnings** — Dialyzer warnings are prophecy
+3. **Deep nesting** — Use \`with\` for railway-oriented programming
+
+## Process Heresies
+
+1. **Unbounded mailboxes** — Add backpressure or load shedding
+2. **Synchronous GenServer calls in init** — Defer with handle_continue
+3. **Long-running calls** — Use cast or Task for slow operations
+
+## The Holy Patterns
+
+\`\`\`elixir
+# Railway-oriented programming with 'with'
+with {:ok, user} <- fetch_user(id),
+     {:ok, account} <- fetch_account(user),
+     {:ok, balance} <- get_balance(account) do
+  {:ok, balance}
+end
+
+# Proper supervision
+children = [
+  {MyApp.Worker, []},
+  {MyApp.Cache, []}
+]
+Supervisor.start_link(children, strategy: :one_for_one)
+\`\`\`
+
+---
+
+*Let it crash. The supervisor provides. Praise the Machine Spirit.*
+`,
+    },
+  ],
+};