@warpgogol/forge 2.8.0 → 2.8.2

package/os/exploration/frontmatter-io.ts

@@ -0,0 +1,77 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Shared exploration note frontmatter I/O — list exploration files and parse
+their YAML frontmatter without validating the shape.
+</purpose>
+<non-goals>
+  <item>Do not validate frontmatter shape — that is the skill's responsibility.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial exploration frontmatter I/O.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { EXPLORATION_DIR } from "./types.ts";
+
+export interface ParsedExplorationNote {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+export function parseExplorationFile(source: string): ParsedExplorationNote {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: source };
+  }
+  return {
+    frontmatter: (YAML.parse(match[1]!) ?? {}) as Record<string, unknown>,
+    body: match[2] ?? "",
+  };
+}
+
+export async function listExplorationFiles(explorationsDirPath: string): Promise<string[]> {
+  const results: string[] = [];
+
+  try {
+    const entries = await fs.readdir(explorationsDirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
+        results.push(entry.name);
+      }
+    }
+  } catch {
+    // Directory doesn't exist or is unreadable — return empty
+  }
+
+  return results.sort();
+}
+
+export async function readAndParseExplorationNote(
+  explorationsDirPath: string,
+  fileName: string,
+): Promise<{ fileName: string; parsed: ParsedExplorationNote } | undefined> {
+  try {
+    const filePath = path.join(explorationsDirPath, fileName);
+    const content = await fs.readFile(filePath, "utf-8");
+    return { fileName, parsed: parseExplorationFile(content) };
+  } catch {
+    return undefined;
+  }
+}
+
+export function serializeExplorationNote(
+  frontmatter: Record<string, unknown>,
+  body: string,
+): string {
+  const fmYaml = YAML.stringify(frontmatter).trimEnd();
+  return `---\n${fmYaml}\n---\n${body}`;
+}
+
+export function getExplorationsDir(workspaceRoot: string): string {
+  return path.join(workspaceRoot, EXPLORATION_DIR);
+}

package/os/exploration/handlers/archive.ts

@@ -0,0 +1,159 @@
+/*
+<MODULE_CONTRACT>
+<purpose>exploration.archive handler — transition an exploration note to archived status.</purpose>
+<non-goals>
+  <item>Do not delete exploration notes — archive is a status transition only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial exploration.archive handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import {
+  readAndParseExplorationNote,
+  serializeExplorationNote,
+  getExplorationsDir,
+} from "../frontmatter-io.ts";
+import { EXPLORATION_SLUG_PATTERN, type ExplorationArchiveResult } from "../types.ts";
+
+function parseRelatedArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((v): v is string => typeof v === "string");
+  }
+  return [];
+}
+
+export async function runExplorationArchive(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ExplorationArchiveResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const explorationsDirPath = getExplorationsDir(workspaceRoot);
+
+  const slug = input.flags["id"] as string | undefined;
+  if (!slug) {
+    return {
+      data: {
+        command: "exploration.archive",
+        status: "error",
+        id: "",
+        previousStatus: "",
+        newStatus: "archived",
+        related: [],
+      },
+      exitCode: 1,
+      summary: "exploration.archive requires --id <slug>",
+    };
+  }
+
+  if (!EXPLORATION_SLUG_PATTERN.test(slug)) {
+    if (outputFormat === "pretty") {
+      logger.info(`Invalid slug: ${slug}. Must be kebab-case, lowercase, latin-only.`);
+    }
+    return {
+      data: {
+        command: "exploration.archive",
+        status: "error",
+        id: slug,
+        previousStatus: "",
+        newStatus: "archived",
+        related: [],
+      },
+      exitCode: 1,
+      summary: `Invalid slug: ${slug}`,
+    };
+  }
+
+  const fileName = `${slug}.md`;
+  const filePath = path.join(explorationsDirPath, fileName);
+  const result = await readAndParseExplorationNote(explorationsDirPath, fileName);
+  if (!result) {
+    if (outputFormat === "pretty") {
+      logger.info(`Exploration note not found: ${slug}`);
+    }
+    return {
+      data: {
+        command: "exploration.archive",
+        status: "error",
+        id: slug,
+        previousStatus: "",
+        newStatus: "archived",
+        related: [],
+      },
+      exitCode: 1,
+      summary: `Exploration note not found: ${slug}`,
+    };
+  }
+
+  const fm = result.parsed.frontmatter;
+  const previousStatus = String(fm["status"] ?? "open");
+  const related = parseRelatedArray(fm["related"]);
+
+  const rfcId = input.flags["rfc"] as string | undefined;
+  if (rfcId && !related.includes(rfcId)) {
+    related.push(rfcId);
+  }
+
+  if (previousStatus === "archived") {
+    if (rfcId) {
+      const updatedFrontmatter: Record<string, unknown> = {
+        ...fm,
+        status: "archived",
+        related,
+      };
+      const updatedContent = serializeExplorationNote(updatedFrontmatter, result.parsed.body);
+      await fs.writeFile(filePath, updatedContent, "utf-8");
+    }
+    if (outputFormat === "pretty") {
+      logger.info(`Exploration note ${slug} is already archived (no-op).`);
+    }
+    return {
+      data: {
+        command: "exploration.archive",
+        status: "ok",
+        id: slug,
+        previousStatus: "archived",
+        newStatus: "archived",
+        related,
+      },
+      exitCode: 0,
+      summary: `Exploration note ${slug} is already archived (no-op)`,
+    };
+  }
+
+  const updatedFrontmatter: Record<string, unknown> = {
+    ...fm,
+    status: "archived",
+    related,
+  };
+
+  const updatedContent = serializeExplorationNote(updatedFrontmatter, result.parsed.body);
+  await fs.writeFile(filePath, updatedContent, "utf-8");
+
+  if (outputFormat === "pretty") {
+    logger.success(`Archived exploration note: ${slug} (${previousStatus} → archived)`);
+    if (rfcId) {
+      logger.info(`Related RFC: ${rfcId}`);
+    }
+  }
+
+  return {
+    data: {
+      command: "exploration.archive",
+      status: "ok",
+      id: slug,
+      previousStatus,
+      newStatus: "archived",
+      related,
+    },
+    summary: `Archived exploration note: ${slug} (${previousStatus} → archived)`,
+  };
+}

package/os/exploration/handlers/list.ts

@@ -0,0 +1,77 @@
+/*
+<MODULE_CONTRACT>
+<purpose>exploration.list handler — list all exploration notes with metadata.</purpose>
+<non-goals>
+  <item>Do not validate frontmatter shape — listing is metadata-only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial exploration.list handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import path from "node:path";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import {
+  listExplorationFiles,
+  readAndParseExplorationNote,
+  getExplorationsDir,
+} from "../frontmatter-io.ts";
+import type { ExplorationListEntry, ExplorationListResult, ExplorationStatus } from "../types.ts";
+
+export async function runExplorationList(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ExplorationListResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const explorationsDirPath = getExplorationsDir(workspaceRoot);
+
+  const filterStatus = input.flags["status"] as string | undefined;
+
+  const files = await listExplorationFiles(explorationsDirPath);
+  const entries: ExplorationListEntry[] = [];
+
+  for (const fileName of files) {
+    const result = await readAndParseExplorationNote(explorationsDirPath, fileName);
+    if (!result) continue;
+
+    const fm = result.parsed.frontmatter;
+    const status = String(fm["status"] ?? "") as ExplorationStatus;
+
+    if (filterStatus && status !== filterStatus) continue;
+
+    entries.push({
+      id: String(fm["id"] ?? path.basename(fileName, ".md")),
+      title: String(fm["title"] ?? ""),
+      status,
+      createdAt: String(fm["createdAt"] ?? ""),
+    });
+  }
+
+  if (outputFormat === "pretty") {
+    if (entries.length === 0) {
+      logger.info("No exploration notes found.");
+    } else {
+      logger.section(`Exploration notes (${entries.length})`);
+      for (const entry of entries) {
+        logger.info(
+          `${entry.id}  ${entry.status.padEnd(10)} ${entry.createdAt.padEnd(12)} ${entry.title}`,
+        );
+      }
+    }
+  }
+
+  return {
+    data: {
+      command: "exploration.list",
+      status: "ok",
+      count: entries.length,
+      explorations: entries,
+    },
+    summary: `${entries.length} exploration note(s) found`,
+  };
+}

package/os/exploration/handlers/show.ts

@@ -0,0 +1,107 @@
+/*
+<MODULE_CONTRACT>
+<purpose>exploration.show handler — return the full content of a single exploration note.</purpose>
+<non-goals>
+  <item>Do not validate frontmatter shape — show returns raw parsed content.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial exploration.show handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { readAndParseExplorationNote, getExplorationsDir } from "../frontmatter-io.ts";
+import type { ExplorationNote, ExplorationShowResult, ExplorationStatus } from "../types.ts";
+
+function parseRelatedArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((v): v is string => typeof v === "string");
+  }
+  return [];
+}
+
+export async function runExplorationShow(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ExplorationShowResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const explorationsDirPath = getExplorationsDir(workspaceRoot);
+
+  const slug = input.flags["id"] as string | undefined;
+  if (!slug) {
+    return {
+      data: {
+        command: "exploration.show",
+        status: "error",
+        note: {
+          id: "",
+          title: "",
+          createdAt: "",
+          status: "open",
+          related: [],
+          body: "",
+        },
+      },
+      exitCode: 1,
+      summary: "exploration.show requires --id <slug>",
+    };
+  }
+
+  const fileName = `${slug}.md`;
+  const result = await readAndParseExplorationNote(explorationsDirPath, fileName);
+  if (!result) {
+    if (outputFormat === "pretty") {
+      logger.info(`Exploration note not found: ${slug}`);
+    }
+    return {
+      data: {
+        command: "exploration.show",
+        status: "error",
+        note: {
+          id: slug,
+          title: "",
+          createdAt: "",
+          status: "open",
+          related: [],
+          body: "",
+        },
+      },
+      exitCode: 1,
+      summary: `Exploration note not found: ${slug}`,
+    };
+  }
+
+  const fm = result.parsed.frontmatter;
+  const note: ExplorationNote = {
+    id: String(fm["id"] ?? slug),
+    title: String(fm["title"] ?? ""),
+    createdAt: String(fm["createdAt"] ?? ""),
+    status: String(fm["status"] ?? "open") as ExplorationStatus,
+    related: parseRelatedArray(fm["related"]),
+    body: result.parsed.body,
+  };
+
+  if (outputFormat === "pretty") {
+    logger.section(`Exploration: ${note.title}`);
+    logger.info(`ID: ${note.id}  Status: ${note.status}  Created: ${note.createdAt}`);
+    if (note.related.length > 0) {
+      logger.info(`Related: ${note.related.join(", ")}`);
+    }
+    logger.info("");
+    logger.info(note.body.trim());
+  }
+
+  return {
+    data: {
+      command: "exploration.show",
+      status: "ok",
+      note,
+    },
+    summary: `Exploration note: ${note.id}`,
+  };
+}

package/os/exploration/index.ts

@@ -0,0 +1,25 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the exploration domain — types, constants, module, and handlers.</purpose>
+<non-goals>
+  <item>Do not implement exploration logic here; delegate to handlers/ and exploration.module.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: expose forgeExplorationModule and exploration types from the exploration domain.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgeExplorationModule } from "./exploration.module.ts";
+export { runExplorationList } from "./handlers/list.ts";
+export { runExplorationShow } from "./handlers/show.ts";
+export { runExplorationArchive } from "./handlers/archive.ts";
+export type {
+  ExplorationStatus,
+  ExplorationNote,
+  ExplorationListEntry,
+  ExplorationListResult,
+  ExplorationShowResult,
+  ExplorationArchiveResult,
+} from "./types.ts";
+export { EXPLORATION_STATUSES, EXPLORATION_DIR, EXPLORATION_SLUG_PATTERN } from "./types.ts";

package/os/exploration/types.ts

@@ -0,0 +1,65 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Defines types and constants for managing exploration notes: statuses,
+frontmatter shape, list/show/archive result types.
+</purpose>
+<non-goals>
+  <item>Do not implement exploration processing logic here.</item>
+  <item>Do not handle user input or command execution.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial exploration types and constants.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type ExplorationStatus = "open" | "explored" | "archived";
+
+export const EXPLORATION_STATUSES: readonly ExplorationStatus[] = [
+  "open",
+  "explored",
+  "archived",
+] as const;
+
+export interface ExplorationNote {
+  id: string;
+  title: string;
+  createdAt: string;
+  status: ExplorationStatus;
+  related: string[];
+  body: string;
+}
+
+export interface ExplorationListEntry {
+  id: string;
+  title: string;
+  status: ExplorationStatus;
+  createdAt: string;
+}
+
+export interface ExplorationListResult {
+  command: "exploration.list";
+  status: "ok";
+  count: number;
+  explorations: ExplorationListEntry[];
+}
+
+export interface ExplorationShowResult {
+  command: "exploration.show";
+  status: "ok" | "error";
+  note: ExplorationNote;
+}
+
+export interface ExplorationArchiveResult {
+  command: "exploration.archive";
+  status: "ok" | "error";
+  id: string;
+  previousStatus: string;
+  newStatus: "archived";
+  related: string[];
+}
+
+export const EXPLORATION_DIR = "docs/explorations";
+
+export const EXPLORATION_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;