@warpgogol/forge 2.8.0 → 2.8.2

package/os/session/handlers/save.ts

@@ -0,0 +1,348 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+session.save handler — converts raw ATIF files from docs/sessions/.raw/ to
+structured markdown in docs/sessions/ with auto-extracted metadata.
+Deterministic only — no LLM/intelligent annotation (that is fo-session-save skill).
+</purpose>
+<non-goals>
+  <item>Does not generate semantic summaries or decisions — that is the fo-session-save skill.</item>
+  <item>Does not archive sessions — that is session.archive.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: implement session.save command handler.</item>
+  <item>Replace fs.unlink with trashPath for raw file deletion (trash bin for LLM-initiated deletions).</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import YAML from "yaml";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { parseAtif, messagesToTranscriptMarkdown } from "../atif-parser.ts";
+import { trashPath } from "../../../src/utils/fs-trash.ts";
+import {
+  SESSION_DIR,
+  SESSION_RAW_SUBDIR,
+  type SessionType,
+  type SessionSaveResult,
+  type SessionSaveSkip,
+} from "../types.ts";
+
+const RFC_PATTERN = /\bRFC-\d{4}\b/g;
+const FILE_PATH_PATTERN = /\b(?:packages|docs|services|systems|tools|scripts)\/[^\s"'`<>|]+/g;
+const COMMIT_HASH_PATTERN = /\b[0-9a-f]{7,40}\b/g;
+const COMMAND_PATTERN =
+  /\b(?:session|rfc|adr|plan|audit|docs|mission|forge|compass|werkstatt|spec|naming|workflow|bordbuch|sternsystem|release)\.\w+/g;
+
+const TYPE_INDICATORS: Array<{ type: SessionType; patterns: RegExp[] }> = [
+  { type: "grilling", patterns: [/grilling/i, /\/grilling/i, /fo-idea.*plan/i] },
+  {
+    type: "mission",
+    patterns: [/mission\.open/i, /mission\.materialize/i, /mission\.reconcile/i, /mission\.close/i],
+  },
+  {
+    type: "implementation",
+    patterns: [/rfc\.implement\.stamp/i, /implement:\s/i, /fo-idea-implement/i],
+  },
+  { type: "review", patterns: [/fo-review/i, /review:\s/i] },
+  { type: "fix", patterns: [/fo-fix/i, /fix:\s/i] },
+];
+
+function extractRfcIds(content: string): string[] {
+  const matches = content.match(RFC_PATTERN);
+  return matches ? [...new Set(matches)] : [];
+}
+
+function extractFilePaths(content: string): string[] {
+  const matches = content.match(FILE_PATH_PATTERN);
+  return matches ? [...new Set(matches)] : [];
+}
+
+function extractCommitHashes(content: string): string[] {
+  const matches = content.match(COMMIT_HASH_PATTERN);
+  if (!matches) return [];
+  // Filter to plausible git hashes (7-40 hex chars, but exclude pure version numbers)
+  const filtered = matches.filter((h) => {
+    // Exclude strings that look like version numbers (e.g. 1.0.0)
+    if (/^\d+$/.test(h) && h.length <= 8) return false;
+    return true;
+  });
+  return [...new Set(filtered)];
+}
+
+function extractCommands(content: string): string[] {
+  const matches = content.match(COMMAND_PATTERN);
+  return matches ? [...new Set(matches)] : [];
+}
+
+function detectSessionTypes(content: string): SessionType[] {
+  const detected: SessionType[] = [];
+  for (const { type, patterns } of TYPE_INDICATORS) {
+    if (patterns.some((p) => p.test(content))) {
+      detected.push(type);
+    }
+  }
+  if (detected.length === 0) {
+    return ["freeform"];
+  }
+  return detected;
+}
+
+function computeSessionId(rawContent: string, timestamp: Date): string {
+  const hash = createHash("sha256").update(rawContent).digest("hex").slice(0, 6);
+  const parts = [
+    timestamp.getFullYear(),
+    String(timestamp.getMonth() + 1).padStart(2, "0"),
+    String(timestamp.getDate()).padStart(2, "0"),
+    String(timestamp.getHours()).padStart(2, "0"),
+    String(timestamp.getMinutes()).padStart(2, "0"),
+    String(timestamp.getSeconds()).padStart(2, "0"),
+  ];
+  return `${parts.join("-")}-${hash}`;
+}
+
+function extractTimestampFromContent(content: string): Date | null {
+  // Try to find an ISO 8601 timestamp in the content
+  const isoMatch = content.match(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:?\d{2}|Z)?/);
+  if (isoMatch) {
+    const date = new Date(isoMatch[0].replace(" ", "T"));
+    if (!isNaN(date.getTime())) return date;
+  }
+  // Try date-only
+  const dateMatch = content.match(/\d{4}-\d{2}-\d{2}/);
+  if (dateMatch) {
+    const date = new Date(dateMatch[0] + "T00:00:00");
+    if (!isNaN(date.getTime())) return date;
+  }
+  return null;
+}
+
+function buildSessionMarkdown(
+  id: string,
+  timestamp: Date,
+  types: SessionType[],
+  metadata: {
+    relatedRfcs: string[];
+    relatedArtifacts: string[];
+    commits: string[];
+    files: string[];
+    commands: string[];
+  },
+  transcriptMarkdown: string,
+): string {
+  const isoDate = timestamp.toISOString();
+  const frontmatter: Record<string, unknown> = {
+    id,
+    date: isoDate,
+    duration: null,
+    types,
+    summary: "",
+    relatedRfcs: metadata.relatedRfcs,
+    relatedArtifacts: metadata.relatedArtifacts,
+    decisions: [],
+    commits: metadata.commits,
+    files: metadata.files,
+    commands: metadata.commands,
+  };
+
+  const yamlStr = YAML.stringify(frontmatter, { lineWidth: 0 });
+  return `---\n${yamlStr}---\n\n# Session: ${id}\n\n## Transcript\n\n${transcriptMarkdown}\n`;
+}
+
+export async function runSessionSave(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<SessionSaveResult & { skipped: SessionSaveSkip[] }>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const sessionDirPath = path.join(workspaceRoot, SESSION_DIR);
+  const rawDirPath = path.join(sessionDirPath, SESSION_RAW_SUBDIR);
+
+  const dryRun = context.dryRun || input.flags["dry-run"] === true;
+  const keepRaw = input.flags["keep-raw"] === true;
+  const rawFileFlag = input.flags["raw-file"] as string | undefined;
+
+  // Determine which raw files to process
+  let rawFiles: string[];
+  if (rawFileFlag) {
+    const resolvedPath = path.isAbsolute(rawFileFlag)
+      ? rawFileFlag
+      : path.join(workspaceRoot, rawFileFlag);
+    try {
+      await fs.access(resolvedPath);
+    } catch {
+      throw new Error(`Raw file not found: ${rawFileFlag}`);
+    }
+    rawFiles = [
+      path.isAbsolute(rawFileFlag)
+        ? path.relative(rawDirPath, resolvedPath)
+        : rawFileFlag.replace(`${SESSION_DIR}/${SESSION_RAW_SUBDIR}/`, ""),
+    ];
+  } else {
+    try {
+      const entries = await fs.readdir(rawDirPath, { withFileTypes: true });
+      rawFiles = entries.filter((e) => e.isFile()).map((e) => e.name);
+    } catch {
+      rawFiles = [];
+    }
+  }
+
+  if (rawFiles.length === 0) {
+    if (outputFormat === "pretty") {
+      logger.info("No raw files to process.");
+    }
+    return {
+      data: {
+        command: "session.save",
+        status: "ok",
+        file: "",
+        rawFile: "",
+        rawDeleted: false,
+        id: "",
+        types: [],
+        extractedMetadata: {
+          relatedRfcs: [],
+          relatedArtifacts: [],
+          commits: [],
+          files: [],
+          commands: [],
+        },
+        dryRun,
+        skipped: [],
+      },
+      summary: "No raw files to process",
+    };
+  }
+
+  const saved: SessionSaveResult[] = [];
+  const skipped: SessionSaveSkip[] = [];
+
+  for (const rawFileName of rawFiles) {
+    const rawFilePath = path.join(rawDirPath, rawFileName);
+    let rawContent: string;
+    try {
+      rawContent = await fs.readFile(rawFilePath, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        skipped.push({ rawFile: rawFileName, reason: "already processed by another process" });
+        continue;
+      }
+      throw err;
+    }
+
+    // Parse ATIF
+    const atifResult = parseAtif(rawContent);
+    const transcriptText = messagesToTranscriptMarkdown(atifResult.messages);
+
+    // Extract metadata
+    const fullContent = rawContent;
+    const relatedRfcs = extractRfcIds(fullContent);
+    const relatedArtifacts = extractFilePaths(fullContent);
+    const commits = extractCommitHashes(fullContent);
+    const files = extractFilePaths(fullContent);
+    const commands = extractCommands(fullContent);
+    const types = detectSessionTypes(fullContent);
+
+    // Compute session id
+    const extractedTimestamp = extractTimestampFromContent(fullContent);
+    const timestamp = extractedTimestamp ?? new Date();
+    const id = computeSessionId(rawContent, timestamp);
+
+    // Check if output already exists (idempotency)
+    const outputFileName = `${id}.md`;
+    const outputPath = path.join(sessionDirPath, outputFileName);
+    const outputRel = path.join(SESSION_DIR, outputFileName);
+
+    try {
+      await fs.access(outputPath);
+      skipped.push({ rawFile: rawFileName, reason: "already converted" });
+      if (outputFormat === "pretty") {
+        logger.info(`Skipped ${rawFileName}: already converted to ${outputRel}`);
+      }
+      continue;
+    } catch {
+      // Output doesn't exist — proceed
+    }
+
+    // Build markdown
+    const markdown = buildSessionMarkdown(
+      id,
+      timestamp,
+      types,
+      { relatedRfcs, relatedArtifacts, commits, files, commands },
+      transcriptText,
+    );
+
+    if (!dryRun) {
+      await fs.mkdir(sessionDirPath, { recursive: true });
+      await fs.writeFile(outputPath, markdown, "utf-8");
+
+      // Delete raw file unless --keep-raw
+      if (!keepRaw) {
+        try {
+          await trashPath(rawFilePath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+            throw err;
+          }
+        }
+      }
+    }
+
+    const result: SessionSaveResult = {
+      command: "session.save",
+      status: "ok",
+      file: outputRel,
+      rawFile: path.join(SESSION_DIR, SESSION_RAW_SUBDIR, rawFileName),
+      rawDeleted: !dryRun && !keepRaw,
+      id,
+      types,
+      extractedMetadata: {
+        relatedRfcs,
+        relatedArtifacts,
+        commits,
+        files,
+        commands,
+      },
+      dryRun,
+    };
+    saved.push(result);
+
+    if (outputFormat === "pretty") {
+      logger.success(`Saved session ${id} to ${outputRel}`);
+    }
+  }
+
+  const firstSaved = saved[0];
+  return {
+    data: firstSaved
+      ? { ...firstSaved, skipped }
+      : {
+          command: "session.save" as const,
+          status: "ok" as const,
+          file: "",
+          rawFile: "",
+          rawDeleted: false,
+          id: "",
+          types: [],
+          extractedMetadata: {
+            relatedRfcs: [],
+            relatedArtifacts: [],
+            commits: [],
+            files: [],
+            commands: [],
+          },
+          dryRun,
+          skipped,
+        },
+    summary: dryRun
+      ? `[dry-run] Would save ${saved.length} session(s), skip ${skipped.length}`
+      : `Saved ${saved.length} session(s), skipped ${skipped.length}`,
+  };
+}

package/os/session/handlers/validate.ts

@@ -0,0 +1,250 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+session.validate handler — checks session frontmatter schema (SES-01),
+id-filename match (SES-02), RFC-id existence (SES-03), raw file hygiene
+(SES-04), non-markdown file detection (SES-05), and missing checkpoint
+fields in implementation/mission sessions (SES-06, RFC-0884).
+</purpose>
+<non-goals>
+  <item>Does not move or modify files — that is session.archive.</item>
+  <item>Does not check transcript content quality — that is the fo-session-save skill.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: implement session.validate command handler.</item>
+  <item>RFC-0884: add SES-06 warning for missing checkpoint fields in implementation/mission sessions.</item>
+</CHANGE_SUMMARY>
+*/
+
+import path from "node:path";
+import {
+  listSessionFiles,
+  listNonMarkdownSessionFiles,
+  listRawFiles,
+  readAndParseSession,
+} from "../frontmatter-io.ts";
+import { listRfcFiles, readAndParseRfc } from "../../rfc/frontmatter-io.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import {
+  SESSION_DIR,
+  SESSION_KNOWN_KEYS,
+  SESSION_REQUIRED_KEYS,
+  SESSION_TYPES,
+  SES_RULES,
+  type SessionValidationResult,
+  type SessionValidationViolation,
+} from "../types.ts";
+
+const RFC_DIR = "docs/rfcs";
+
+async function loadRfcIds(workspaceRoot: string): Promise<Set<string>> {
+  const rfcIds = new Set<string>();
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+  const files = await listRfcFiles(rfcDirPath);
+  for (const fileName of files) {
+    const result = await readAndParseRfc(rfcDirPath, fileName);
+    const id = result && "parsed" in result ? String(result.parsed.frontmatter["id"] ?? "") : "";
+    if (id) rfcIds.add(id);
+  }
+  return rfcIds;
+}
+
+export async function runSessionValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<SessionValidationResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const sessionDirPath = path.join(workspaceRoot, SESSION_DIR);
+
+  const targetId = input.flags["id"] as string | undefined;
+
+  const allFiles = await listSessionFiles(sessionDirPath);
+  const filesToValidate = targetId
+    ? allFiles.filter((f) => path.basename(f).toLowerCase().startsWith(targetId.toLowerCase()))
+    : allFiles;
+
+  if (filesToValidate.length === 0) {
+    if (outputFormat === "pretty") {
+      logger.info("No session files found to validate.");
+    }
+    return {
+      data: {
+        command: "session.validate",
+        status: "pass",
+        violations: [],
+        checked: 0,
+      },
+      summary: "No session files found to validate",
+    };
+  }
+
+  const knownRfcIds = await loadRfcIds(workspaceRoot);
+  const knownKeys = new Set<string>(SESSION_KNOWN_KEYS);
+  const violations: SessionValidationViolation[] = [];
+
+  for (const fileName of filesToValidate) {
+    const result = await readAndParseSession(sessionDirPath, fileName);
+    if (!result) continue;
+
+    const fm = result.parsed.frontmatter;
+    const id = String(fm["id"] ?? "");
+    const relFile = path.join(SESSION_DIR, fileName);
+    const basename = path.basename(fileName, ".md");
+
+    // SES-01: Required frontmatter fields
+    for (const key of SESSION_REQUIRED_KEYS) {
+      if (!(key in fm) || fm[key] === undefined || fm[key] === null) {
+        violations.push({
+          rule: SES_RULES.SES_01,
+          file: relFile,
+          message: `Required field "${key}" is missing`,
+          severity: "error",
+        });
+      }
+    }
+
+    // SES-01: Check types is a valid array
+    // typesArray is also used by SES-06 below — hoisted here to make the coupling explicit.
+    const typesValue = fm["types"];
+    const typesArray = Array.isArray(typesValue) ? (typesValue as string[]) : [];
+    if (Array.isArray(typesValue)) {
+      for (const t of typesValue) {
+        if (!SESSION_TYPES.includes(t as never)) {
+          violations.push({
+            rule: SES_RULES.SES_01,
+            file: relFile,
+            message: `Invalid session type "${t}". Must be one of: ${SESSION_TYPES.join(", ")}`,
+            severity: "error",
+          });
+        }
+      }
+    } else if (typesValue !== undefined) {
+      violations.push({
+        rule: SES_RULES.SES_01,
+        file: relFile,
+        message: `Field "types" must be an array`,
+        severity: "error",
+      });
+    }
+
+    // SES-01: Warn on unknown keys
+    for (const key of Object.keys(fm)) {
+      if (!knownKeys.has(key)) {
+        violations.push({
+          rule: SES_RULES.SES_01,
+          file: relFile,
+          message: `Unknown frontmatter key "${key}"`,
+          severity: "warning",
+        });
+      }
+    }
+
+    // SES-02: id matches filename
+    if (id && id !== basename) {
+      violations.push({
+        rule: SES_RULES.SES_02,
+        file: relFile,
+        message: `id "${id}" does not match filename "${basename}"`,
+        severity: "error",
+      });
+    }
+
+    // SES-03: relatedRfcs reference existing RFCs
+    const relatedRfcs = Array.isArray(fm["relatedRfcs"]) ? (fm["relatedRfcs"] as string[]) : [];
+    for (const rfcId of relatedRfcs) {
+      if (!knownRfcIds.has(rfcId)) {
+        violations.push({
+          rule: SES_RULES.SES_03,
+          file: relFile,
+          message: `relatedRfcs references non-existent RFC "${rfcId}"`,
+          severity: "error",
+        });
+      }
+    }
+
+    // SES-06: Missing checkpoint fields in implementation/mission sessions
+    // typesArray is extracted by SES-01 above.
+    const isImplOrMission = typesArray.includes("implementation") || typesArray.includes("mission");
+    if (isImplOrMission) {
+      const hasCheckpointFields =
+        "systemDelta" in fm ||
+        "diagrams" in fm ||
+        "evidence" in fm ||
+        "remainingIssues" in fm ||
+        "checkpoint" in fm;
+      if (!hasCheckpointFields) {
+        violations.push({
+          rule: SES_RULES.SES_06,
+          file: relFile,
+          message:
+            "Implementation/mission session missing checkpoint frontmatter fields (systemDelta, diagrams, evidence, remainingIssues, checkpoint). Agent should populate these during fo-session-save.",
+          severity: "warning",
+        });
+      }
+    }
+  }
+
+  // SES-04: Raw files in .raw/ that haven't been processed (warning)
+  const rawFiles = await listRawFiles(sessionDirPath);
+  for (const rawFile of rawFiles) {
+    violations.push({
+      rule: SES_RULES.SES_04,
+      file: path.join(SESSION_DIR, ".raw", rawFile),
+      message: `Unprocessed raw file in .raw/ — run session.save to convert`,
+      severity: "warning",
+    });
+  }
+
+  // SES-05: Non-markdown files in docs/sessions/ (excluding .raw/ and archive/)
+  const nonMdFiles = await listNonMarkdownSessionFiles(sessionDirPath);
+  for (const nonMdFile of nonMdFiles) {
+    violations.push({
+      rule: SES_RULES.SES_05,
+      file: path.join(SESSION_DIR, nonMdFile),
+      message: `Non-markdown file in docs/sessions/ — only .md files are allowed (excluding .raw/ and archive/)`,
+      severity: "error",
+    });
+  }
+
+  const hasErrors = violations.some((v) => v.severity === "error");
+  const resultStatus = hasErrors ? "fail" : "pass";
+
+  if (outputFormat === "pretty") {
+    if (violations.length === 0) {
+      logger.success(`All ${filesToValidate.length} session file(s) passed validation.`);
+    } else {
+      logger.section(`Session Validation (${filesToValidate.length} file(s))`);
+      for (const v of violations) {
+        const prefix = v.severity === "error" ? "ERROR" : "WARN";
+        logger[v.severity === "error" ? "error" : "warn"](
+          `[${prefix}] ${v.rule}: ${v.file}: ${v.message}`,
+        );
+      }
+      const errorCount = violations.filter((v) => v.severity === "error").length;
+      const warnCount = violations.filter((v) => v.severity === "warning").length;
+      if (errorCount > 0) {
+        logger.error(`${errorCount} error(s), ${warnCount} warning(s)`);
+      } else {
+        logger.warn(`${warnCount} warning(s), 0 errors — passed`);
+      }
+    }
+  }
+
+  return {
+    data: {
+      command: "session.validate",
+      status: resultStatus,
+      violations,
+      checked: filesToValidate.length,
+    },
+    exitCode: hasErrors ? 1 : 0,
+    summary: hasErrors
+      ? `${violations.filter((v) => v.severity === "error").length} error(s) found`
+      : `All ${filesToValidate.length} session file(s) passed validation`,
+  };
+}

package/os/session/index.ts

@@ -0,0 +1,50 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the session domain — types, module, and handlers.</purpose>
+<non-goals>
+  <item>Do not implement session logic here; delegate to handlers/ and session.module.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: initial session module barrel.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgeSessionModule } from "./session.module.ts";
+export { runSessionSave } from "./handlers/save.ts";
+export { runSessionArchive } from "./handlers/archive.ts";
+export { runSessionValidate } from "./handlers/validate.ts";
+export { runSessionList } from "./handlers/list.ts";
+export {
+  parseSessionFile,
+  listSessionFiles,
+  listArchivedSessionFiles,
+  readAndParseSession,
+  listNonMarkdownSessionFiles,
+  listRawFiles,
+  type ParsedSession,
+} from "./frontmatter-io.ts";
+export {
+  parseAtif,
+  messagesToTranscriptMarkdown,
+  type AtifMessage,
+  type AtifParseResult,
+} from "./atif-parser.ts";
+export {
+  SESSION_DIR,
+  SESSION_RAW_SUBDIR,
+  SESSION_ARCHIVE_SUBDIR,
+  SESSION_TYPES,
+  SES_RULES,
+  type SessionType,
+  type SessionFrontmatter,
+  type SessionSaveResult,
+  type SessionArchiveResult,
+  type SessionArchiveMove,
+  type SessionArchiveSkip,
+  type SessionValidationResult,
+  type SessionValidationViolation,
+  type SessionListResult,
+  type SessionListEntry,
+  type SesRule,
+} from "./types.ts";