@warpgogol/forge 0.3.1

package/dist/os/session/handlers/archive.js

@@ -0,0 +1,209 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+session.archive handler — moves session files older than --max-age-days from
+docs/sessions/ to docs/sessions/archive/. Bidirectional: files in archive/
+younger than threshold are moved back to docs/sessions/.
+</purpose>
+<non-goals>
+  <item>Does not validate session content — that is session.validate.</item>
+  <item>Does not change session frontmatter — only moves files on disk.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: implement session.archive command handler.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs/promises";
+import path from "node:path";
+import { listSessionFiles, listArchivedSessionFiles, readAndParseSession, } from "../frontmatter-io.js";
+import { SESSION_DIR, SESSION_ARCHIVE_SUBDIR, } from "../types.js";
+const DEFAULT_MAX_AGE_DAYS = 7;
+function parseSessionDate(fm) {
+    const dateStr = String(fm["date"] ?? "");
+    if (!dateStr)
+        return null;
+    const date = new Date(dateStr);
+    return isNaN(date.getTime()) ? null : date;
+}
+function computeAgeDays(sessionDate, now) {
+    const diffMs = now.getTime() - sessionDate.getTime();
+    return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+}
+export async function runSessionArchive(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const sessionDirPath = path.join(workspaceRoot, SESSION_DIR);
+    const archiveDirPath = path.join(sessionDirPath, SESSION_ARCHIVE_SUBDIR);
+    const dryRun = context.dryRun || input.flags["dry-run"] === true;
+    const maxAgeDaysRaw = input.flags["max-age-days"];
+    const maxAgeDays = maxAgeDaysRaw !== undefined
+        ? typeof maxAgeDaysRaw === "string"
+            ? parseInt(maxAgeDaysRaw, 10)
+            : typeof maxAgeDaysRaw === "number"
+                ? maxAgeDaysRaw
+                : DEFAULT_MAX_AGE_DAYS
+        : DEFAULT_MAX_AGE_DAYS;
+    if (isNaN(maxAgeDays) || maxAgeDays <= 0) {
+        throw new Error(`Invalid --max-age-days: must be a positive integer, got "${maxAgeDaysRaw}"`);
+    }
+    const now = new Date();
+    const moved = [];
+    const skipped = [];
+    // Process active files — move to archive if older than threshold
+    const activeFiles = await listSessionFiles(sessionDirPath);
+    for (const fileName of activeFiles) {
+        const result = await readAndParseSession(sessionDirPath, fileName);
+        if (!result) {
+            skipped.push({
+                id: "UNKNOWN",
+                file: path.join(SESSION_DIR, fileName),
+                reason: "unreadable frontmatter",
+            });
+            continue;
+        }
+        const fm = result.parsed.frontmatter;
+        const id = String(fm["id"] ?? "UNKNOWN");
+        const sessionDate = parseSessionDate(fm);
+        const relFile = path.join(SESSION_DIR, fileName);
+        const basename = path.basename(fileName);
+        if (!sessionDate) {
+            skipped.push({ id, file: relFile, reason: "no valid date in frontmatter" });
+            continue;
+        }
+        const ageDays = computeAgeDays(sessionDate, now);
+        if (ageDays > maxAgeDays) {
+            const targetPath = path.join(archiveDirPath, basename);
+            const targetRel = path.join(SESSION_DIR, SESSION_ARCHIVE_SUBDIR, basename);
+            try {
+                await fs.access(targetPath);
+                skipped.push({ id, file: relFile, reason: "destination exists" });
+                continue;
+            }
+            catch {
+                // destination doesn't exist — proceed
+            }
+            if (!dryRun) {
+                await fs.mkdir(archiveDirPath, { recursive: true });
+                try {
+                    await fs.rename(path.join(sessionDirPath, fileName), targetPath);
+                }
+                catch (err) {
+                    if (err.code === "ENOENT") {
+                        skipped.push({ id, file: relFile, reason: "already moved by another process" });
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            moved.push({
+                id,
+                file: targetRel,
+                from: relFile,
+                to: targetRel,
+                ageDays,
+                direction: "into-archive",
+            });
+        }
+        else {
+            skipped.push({
+                id,
+                file: relFile,
+                reason: `age ${ageDays} days < max-age ${maxAgeDays} days`,
+            });
+        }
+    }
+    // Process archived files — move back to active if younger than threshold
+    const archivedFiles = await listArchivedSessionFiles(sessionDirPath);
+    for (const archFileName of archivedFiles) {
+        const archFullPath = path.join(archiveDirPath, archFileName);
+        const result = await readAndParseSession(path.join(sessionDirPath, SESSION_ARCHIVE_SUBDIR), archFileName);
+        if (!result) {
+            skipped.push({
+                id: "UNKNOWN",
+                file: path.join(SESSION_DIR, SESSION_ARCHIVE_SUBDIR, archFileName),
+                reason: "unreadable frontmatter",
+            });
+            continue;
+        }
+        const fm = result.parsed.frontmatter;
+        const id = String(fm["id"] ?? "UNKNOWN");
+        const sessionDate = parseSessionDate(fm);
+        const archRelFile = path.join(SESSION_DIR, SESSION_ARCHIVE_SUBDIR, archFileName);
+        const basename = path.basename(archFileName);
+        if (!sessionDate) {
+            skipped.push({ id, file: archRelFile, reason: "no valid date in frontmatter" });
+            continue;
+        }
+        const ageDays = computeAgeDays(sessionDate, now);
+        if (ageDays <= maxAgeDays) {
+            const targetPath = path.join(sessionDirPath, basename);
+            const targetRel = path.join(SESSION_DIR, basename);
+            try {
+                await fs.access(targetPath);
+                skipped.push({ id, file: archRelFile, reason: "destination exists" });
+                continue;
+            }
+            catch {
+                // destination doesn't exist — proceed
+            }
+            if (!dryRun) {
+                try {
+                    await fs.rename(archFullPath, targetPath);
+                }
+                catch (err) {
+                    if (err.code === "ENOENT") {
+                        skipped.push({ id, file: archRelFile, reason: "already moved by another process" });
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            moved.push({
+                id,
+                file: targetRel,
+                from: archRelFile,
+                to: targetRel,
+                ageDays,
+                direction: "out-of-archive",
+            });
+        }
+        else {
+            skipped.push({
+                id,
+                file: archRelFile,
+                reason: `age ${ageDays} days > max-age ${maxAgeDays} days (already archived)`,
+            });
+        }
+    }
+    if (outputFormat === "pretty") {
+        if (dryRun) {
+            logger.info(`[dry-run] session.archive: would move ${moved.length} file(s), skip ${skipped.length}`);
+        }
+        else {
+            logger.success(`session.archive: moved ${moved.length} file(s), skipped ${skipped.length}`);
+        }
+        for (const m of moved) {
+            logger.info(`  ${m.direction}: ${m.id} (age ${m.ageDays}d) ${m.from} → ${m.to}`);
+        }
+    }
+    return {
+        data: {
+            command: "session.archive",
+            status: "ok",
+            moved,
+            skipped,
+            maxAgeDays,
+            dryRun,
+        },
+        summary: dryRun
+            ? `[dry-run] Would move ${moved.length} file(s), skip ${skipped.length}`
+            : `Moved ${moved.length} file(s), skipped ${skipped.length}`,
+        nextSteps: [
+            {
+                action: "Run: pnpm exec site-kernel run session.list --json to verify archive status",
+                kind: "optional",
+            },
+        ],
+    };
+}
+//# sourceMappingURL=archive.js.map

package/dist/os/session/handlers/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../../os/session/handlers/archive.ts"],"names":[],"mappings":"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"}

package/dist/os/session/handlers/list.d.ts

@@ -0,0 +1,4 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import { type SessionListResult } from "../types.ts";
+export declare function runSessionList(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<SessionListResult>>;
+//# sourceMappingURL=list.d.ts.map

package/dist/os/session/handlers/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../../os/session/handlers/list.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,iBAAiB,EAGvB,MAAM,aAAa,CAAC;AAUrB,wBAAsB,cAAc,CAClC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC,CA+HhD"}

package/dist/os/session/handlers/list.js

@@ -0,0 +1,147 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+session.list handler — lists session files with optional filters by date
+range, RFC-id, and session type. Parses frontmatter on the fly.
+</purpose>
+<non-goals>
+  <item>Does not validate session content — that is session.validate.</item>
+  <item>Does not modify files in any way.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: implement session.list command handler.</item>
+</CHANGE_SUMMARY>
+*/
+import path from "node:path";
+import { listSessionFiles, listArchivedSessionFiles, readAndParseSession, } from "../frontmatter-io.js";
+import { SESSION_DIR, SESSION_ARCHIVE_SUBDIR, } from "../types.js";
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+function parseDate(dateStr) {
+    if (!DATE_PATTERN.test(dateStr))
+        return null;
+    const date = new Date(dateStr + "T00:00:00Z");
+    return isNaN(date.getTime()) ? null : date;
+}
+export async function runSessionList(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const sessionDirPath = path.join(workspaceRoot, SESSION_DIR);
+    const filterDateFrom = input.flags["date-from"];
+    const filterDateTo = input.flags["date-to"];
+    const filterRfc = input.flags["rfc"];
+    const filterType = input.flags["type"];
+    let dateFrom = null;
+    let dateTo = null;
+    if (filterDateFrom) {
+        dateFrom = parseDate(filterDateFrom);
+        if (!dateFrom) {
+            throw new Error(`Invalid --date-from format, use YYYY-MM-DD. Got: "${filterDateFrom}"`);
+        }
+    }
+    if (filterDateTo) {
+        dateTo = parseDate(filterDateTo);
+        if (!dateTo) {
+            throw new Error(`Invalid --date-to format, use YYYY-MM-DD. Got: "${filterDateTo}"`);
+        }
+    }
+    const entries = [];
+    // Process active files
+    const activeFiles = await listSessionFiles(sessionDirPath);
+    for (const fileName of activeFiles) {
+        const result = await readAndParseSession(sessionDirPath, fileName);
+        if (!result)
+            continue;
+        const fm = result.parsed.frontmatter;
+        const id = String(fm["id"] ?? "");
+        const date = String(fm["date"] ?? "");
+        const types = Array.isArray(fm["types"]) ? fm["types"] : [];
+        const summary = String(fm["summary"] ?? "");
+        const relatedRfcs = Array.isArray(fm["relatedRfcs"]) ? fm["relatedRfcs"] : [];
+        // Apply filters
+        if (filterRfc && !relatedRfcs.includes(filterRfc))
+            continue;
+        if (filterType && !types.includes(filterType))
+            continue;
+        if (dateFrom || dateTo) {
+            const sessionDate = new Date(date);
+            if (isNaN(sessionDate.getTime()))
+                continue;
+            const sessionDay = new Date(sessionDate.toISOString().slice(0, 10) + "T00:00:00Z");
+            if (dateFrom && sessionDay < dateFrom)
+                continue;
+            if (dateTo && sessionDay > dateTo)
+                continue;
+        }
+        entries.push({
+            id,
+            date,
+            types,
+            summary,
+            relatedRfcs,
+            file: path.join(SESSION_DIR, fileName),
+            archived: false,
+        });
+    }
+    // Process archived files
+    const archivedFiles = await listArchivedSessionFiles(sessionDirPath);
+    for (const fileName of archivedFiles) {
+        const result = await readAndParseSession(path.join(sessionDirPath, SESSION_ARCHIVE_SUBDIR), fileName);
+        if (!result)
+            continue;
+        const fm = result.parsed.frontmatter;
+        const id = String(fm["id"] ?? "");
+        const date = String(fm["date"] ?? "");
+        const types = Array.isArray(fm["types"]) ? fm["types"] : [];
+        const summary = String(fm["summary"] ?? "");
+        const relatedRfcs = Array.isArray(fm["relatedRfcs"]) ? fm["relatedRfcs"] : [];
+        // Apply filters
+        if (filterRfc && !relatedRfcs.includes(filterRfc))
+            continue;
+        if (filterType && !types.includes(filterType))
+            continue;
+        if (dateFrom || dateTo) {
+            const sessionDate = new Date(date);
+            if (isNaN(sessionDate.getTime()))
+                continue;
+            const sessionDay = new Date(sessionDate.toISOString().slice(0, 10) + "T00:00:00Z");
+            if (dateFrom && sessionDay < dateFrom)
+                continue;
+            if (dateTo && sessionDay > dateTo)
+                continue;
+        }
+        entries.push({
+            id,
+            date,
+            types,
+            summary,
+            relatedRfcs,
+            file: path.join(SESSION_DIR, SESSION_ARCHIVE_SUBDIR, fileName),
+            archived: true,
+        });
+    }
+    // Sort by date descending (most recent first)
+    entries.sort((a, b) => b.date.localeCompare(a.date));
+    if (outputFormat === "pretty") {
+        if (entries.length === 0) {
+            logger.info("No sessions found matching the given filters.");
+        }
+        else {
+            logger.section(`Sessions (${entries.length})`);
+            for (const entry of entries) {
+                const archTag = entry.archived ? " [archived]" : "";
+                const typesStr = entry.types.join(", ");
+                logger.info(`${entry.id}  ${typesStr.padEnd(20)} ${entry.date}  ${entry.summary}${archTag}`);
+            }
+        }
+    }
+    return {
+        data: {
+            command: "session.list",
+            status: "ok",
+            sessions: entries,
+            count: entries.length,
+        },
+        summary: `${entries.length} session(s) found`,
+    };
+}
+//# sourceMappingURL=list.js.map

package/dist/os/session/handlers/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../../os/session/handlers/list.ts"],"names":[],"mappings":"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"}

package/dist/os/session/handlers/save.d.ts

@@ -0,0 +1,6 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import { type SessionSaveResult, type SessionSaveSkip } from "../types.ts";
+export declare function runSessionSave(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<SessionSaveResult & {
+    skipped: SessionSaveSkip[];
+}>>;
+//# sourceMappingURL=save.d.ts.map

package/dist/os/session/handlers/save.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../../../os/session/handlers/save.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAoHrB,wBAAsB,cAAc,CAClC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,iBAAiB,GAAG;IAAE,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC,CAAC,CAsLjF"}