@nan0web/release 3.2.0 → 3.4.0

package/types/domain/Dashboard/DashboardModel.d.ts

@@ -0,0 +1,273 @@
+/**
+ * @typedef {import('./ReleaseParser.js').TaskItem} TaskItem
+ * @typedef {Object} ProjectDashboardEntry
+ * @property {string} path - Relative project path
+ * @property {string} name - Project name
+ * @property {string} version - Current release version
+ * @property {number} hours - Development hours spent
+ * @property {number} iterations - Test runs / refactor iterations
+ * @property {number} rrs - Release Readiness Score
+ * @property {'wip' | 'closed' | 'unknown'} status - Release state
+ * @property {TaskItem[]} tasks - Parsed tasks from release.md
+ * @property {string} branch - Git branch name
+ * @property {'clean' | 'dirty'} gitStatus - Git workspace status
+ * @property {string} userContent - Raw user.md content
+ * @property {string} releaseContent - Raw release.md content
+ * @property {string} sourceDoc - Relative path to the parsed release document
+ * @property {string} sourceUserDoc - Relative path to user.md
+ * @property {string?} deadline - Project release deadline
+ * @property {number?} daysRemaining - Days remaining until deadline
+ * @property {string?} priority - Priority (0 | 1 | 2 | 3)
+ * @property {number} [releasesCount] - Number of releases found
+ * @property {number} [totalHours] - Total hours across all releases
+ * @property {number} [totalIterations] - Total iterations across all releases
+ * @property {Array<any>} [allReleases] - List of all releases for project
+ *
+ * @typedef {Object} DashboardSummary
+ * @property {number} totalProjects - Total tracked projects
+ * @property {number} totalHours - Sum of hours across projects
+ * @property {number} totalIterations - Sum of iterations
+ * @property {number} wipCount - Active WIP releases
+ * @property {number} closedCount - Closed releases
+ * @property {number} [totalReleases] - Total releases counted
+ */
+/**
+ * DashboardModel - Aggregates release telemetry, tasks and readiness across projects.
+ */
+export class DashboardModel extends ModelAsApp {
+    static registryFile: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static summary: {
+        help: string;
+        default: {
+            totalProjects: number;
+            totalHours: number;
+            totalIterations: number;
+            wipCount: number;
+            closedCount: number;
+        };
+        type: string;
+    };
+    static projects: {
+        help: string;
+        default: () => never[];
+        type: string;
+    };
+    static UI: {
+        aggregating: string;
+        done: string;
+    };
+    static parseUserMetrics: typeof parseUserMetrics;
+    static normalizePriority: typeof normalizePriority;
+    static sortTasks: typeof sortTasks;
+    static versionToPath: typeof versionToPath;
+    /**
+     * @param {Partial<DashboardModel>} [data={}]
+     * @param {Partial<import('@nan0web/ui').ModelAsAppOptions & { gitTelemetry?: any }>} [options={}]
+     */
+    constructor(data?: Partial<DashboardModel>, options?: Partial<import("@nan0web/ui").ModelAsAppOptions & {
+        gitTelemetry?: any;
+    }>);
+    /** @type {string} Path to releases.txt registry file */ registryFile: string;
+    /** @type {DashboardSummary} Aggregated metrics summary */ summary: DashboardSummary;
+    /** @type {ProjectDashboardEntry[]} List of projects with metrics */ projects: ProjectDashboardEntry[];
+    /** @type {any} Optional git telemetry adapter */
+    _gitTelemetry: any;
+    /**
+     * Canonical OLMUI Generator: Yields progress, show, and returns result.
+     * @returns {AsyncGenerator<import('@nan0web/ui').Intent, any, any>}
+     */
+    run(): AsyncGenerator<import("@nan0web/ui").Intent, any, any>;
+    /**
+     * Programmatic aggregation helper
+     * @param {Function} [onProgress]
+     * @returns {Promise<{ summary: DashboardSummary, projects: ProjectDashboardEntry[] }>}
+     */
+    aggregate(onProgress?: Function): Promise<{
+        summary: DashboardSummary;
+        projects: ProjectDashboardEntry[];
+    }>;
+    aggregateStream(): AsyncGenerator<{
+        current: number;
+        total: number;
+        project: string;
+    }, {
+        summary: DashboardSummary;
+        projects: ({
+            name: any;
+            version: any;
+            path: any;
+            status: string;
+            hours: number;
+            iterations: number;
+            rrs: number;
+            branch: any;
+            gitStatus: any;
+            tasks: never[];
+            deadline: null;
+            daysRemaining: null;
+            priority: string;
+            releasesCount: number;
+            totalHours: number;
+            totalIterations: number;
+            allReleases: never[];
+            sourceDoc: string;
+            sourceUserDoc: string;
+            userContent: string;
+            releaseContent: string;
+        } | {
+            path: string;
+            name: string;
+            version: string;
+            hours: number;
+            iterations: number;
+            totalHours: number;
+            totalIterations: number;
+            releasesCount: number;
+            allReleases: {
+                version: any;
+                path: any;
+                hours: number;
+                iterations: number;
+                rrs: number;
+                status: "wip" | "closed" | "unknown";
+                tasks: import("./ReleaseParser.js").TaskItem[];
+                sourceDoc: string;
+            }[];
+            rrs: number;
+            status: "wip" | "closed" | "unknown";
+            tasks: import("./ReleaseParser.js").TaskItem[];
+            branch: any;
+            gitStatus: any;
+            userContent: string;
+            releaseContent: string;
+            sourceDoc: string;
+            sourceUserDoc: string;
+            deadline: any;
+            daysRemaining: number | null;
+            priority: "0" | "1" | "2" | "3";
+        })[];
+    }, unknown>;
+    #private;
+}
+export type TaskItem = import("./ReleaseParser.js").TaskItem;
+export type ProjectDashboardEntry = {
+    /**
+     * - Relative project path
+     */
+    path: string;
+    /**
+     * - Project name
+     */
+    name: string;
+    /**
+     * - Current release version
+     */
+    version: string;
+    /**
+     * - Development hours spent
+     */
+    hours: number;
+    /**
+     * - Test runs / refactor iterations
+     */
+    iterations: number;
+    /**
+     * - Release Readiness Score
+     */
+    rrs: number;
+    /**
+     * - Release state
+     */
+    status: "wip" | "closed" | "unknown";
+    /**
+     * - Parsed tasks from release.md
+     */
+    tasks: TaskItem[];
+    /**
+     * - Git branch name
+     */
+    branch: string;
+    /**
+     * - Git workspace status
+     */
+    gitStatus: "clean" | "dirty";
+    /**
+     * - Raw user.md content
+     */
+    userContent: string;
+    /**
+     * - Raw release.md content
+     */
+    releaseContent: string;
+    /**
+     * - Relative path to the parsed release document
+     */
+    sourceDoc: string;
+    /**
+     * - Relative path to user.md
+     */
+    sourceUserDoc: string;
+    /**
+     * - Project release deadline
+     */
+    deadline: string | null;
+    /**
+     * - Days remaining until deadline
+     */
+    daysRemaining: number | null;
+    /**
+     * - Priority (0 | 1 | 2 | 3)
+     */
+    priority: string | null;
+    /**
+     * - Number of releases found
+     */
+    releasesCount?: number | undefined;
+    /**
+     * - Total hours across all releases
+     */
+    totalHours?: number | undefined;
+    /**
+     * - Total iterations across all releases
+     */
+    totalIterations?: number | undefined;
+    /**
+     * - List of all releases for project
+     */
+    allReleases?: any[] | undefined;
+};
+export type DashboardSummary = {
+    /**
+     * - Total tracked projects
+     */
+    totalProjects: number;
+    /**
+     * - Sum of hours across projects
+     */
+    totalHours: number;
+    /**
+     * - Sum of iterations
+     */
+    totalIterations: number;
+    /**
+     * - Active WIP releases
+     */
+    wipCount: number;
+    /**
+     * - Closed releases
+     */
+    closedCount: number;
+    /**
+     * - Total releases counted
+     */
+    totalReleases?: number | undefined;
+};
+import { ModelAsApp } from '@nan0web/ui';
+import { parseUserMetrics } from './ReleaseParser.js';
+import { normalizePriority } from './ReleaseParser.js';
+import { sortTasks } from './ReleaseParser.js';
+import { versionToPath } from './ReleaseDiscovery.js';

package/types/domain/Dashboard/GitTelemetry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reset internal Git caches (useful for testing or cache invalidation)
+ */
+export function resetGitCache(): void;
+/**
+ * Retrieve git branch and workspace status (clean / dirty)
+ * @param {string} [projectDir]
+ * @returns {{ branch: string, gitStatus: 'clean' | 'dirty' }}
+ */
+export function getGitInfo(projectDir?: string): {
+    branch: string;
+    gitStatus: "clean" | "dirty";
+};
+/**
+ * Retrieve development hours and iterations from git commit log
+ * @param {string} [projectDir]
+ * @param {string} [releasePath]
+ * @returns {{ hours: number, iterations: number }}
+ */
+export function getGitCommitTelemetry(projectDir?: string, releasePath?: string): {
+    hours: number;
+    iterations: number;
+};

package/types/domain/Dashboard/ReleaseDiscovery.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Parse semver string into [major, minor, patch] numbers
+ * @param {string} [v='']
+ * @returns {[number, number, number]}
+ */
+export function parseSemver(v?: string): [number, number, number];
+/**
+ * Compare two semver strings in descending order
+ * @param {string} [a='']
+ * @param {string} [b='']
+ * @returns {number}
+ */
+export function compareSemverDesc(a?: string, b?: string): number;
+/**
+ * Format release version to path segments e.g. "1.0.0" -> "1/0/v1.0.0"
+ * @param {string} [version='']
+ * @returns {string}
+ */
+export function versionToPath(version?: string): string;
+/**
+ * Check whether a document exists in the virtual database
+ * @param {any} db
+ * @param {string} path
+ * @returns {Promise<boolean>}
+ */
+export function documentExists(db: any, path: string): Promise<boolean>;
+/**
+ * Load release doc (release.md, task.md, plan.md) and extract tasks
+ * @param {any} db
+ * @param {string} releaseDir
+ * @returns {Promise<{ releaseContent: string, sourceDoc: string, tasks: import('./ReleaseParser.js').TaskItem[] }>}
+ */
+export function loadReleaseDoc(db: any, releaseDir: string): Promise<{
+    releaseContent: string;
+    sourceDoc: string;
+    tasks: import("./ReleaseParser.js").TaskItem[];
+}>;
+/**
+ * Discover release version directories using database listDir
+ * @param {any} db
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{ version: string, path: string }>>}
+ */
+export function discoverReleases(db: any, projectRoot: string): Promise<Array<{
+    version: string;
+    path: string;
+}>>;

package/types/domain/Dashboard/ReleaseParser.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @typedef {Object} TaskItem
+ * @property {string} content - Task title or description
+ * @property {string} status - todo | InProgress | Done
+ * @property {string} slug - Task slug / identifier
+ * @property {'0' | '1' | '2' | '3'} [priority] - Numeric priority
+ */
+/**
+ * Parse frontmatter YAML from markdown text
+ * @param {*} input
+ * @returns {Record<string, any>}
+ */
+export function parseFrontmatter(input: any): Record<string, any>;
+/**
+ * Normalize priority to numeric string '0' | '1' | '2' | '3'
+ * @param {any} input
+ * @returns {'0' | '1' | '2' | '3'}
+ */
+export function normalizePriority(input: any): "0" | "1" | "2" | "3";
+/**
+ * Extract clean task items from release markdown
+ * @param {*} input
+ * @returns {TaskItem[]}
+ */
+export function extractTasks(input: any): TaskItem[];
+/**
+ * Calculate days remaining until deadline
+ * @param {string} [deadlineStr]
+ * @returns {number | null}
+ */
+export function calculateDaysRemaining(deadlineStr?: string): number | null;
+/**
+ * Parse user.md content for telemetry metrics (hours, iterations, RRS) across languages
+ * @param {*} [input]
+ * @returns {{ hours: number, iterations: number, rrs: number }}
+ */
+export function parseUserMetrics(input?: any): {
+    hours: number;
+    iterations: number;
+    rrs: number;
+};
+/**
+ * Resolve priority from frontmatter or days remaining
+ * @param {Record<string, any>} fm
+ * @param {number | null} daysRemaining
+ * @returns {'0' | '1' | '2' | '3'}
+ */
+export function resolvePriority(fm?: Record<string, any>, daysRemaining?: number | null): "0" | "1" | "2" | "3";
+/**
+ * Sort tasks by criteria ('priority', 'status', 'alphabetical')
+ * @param {TaskItem[]} [tasks=[]]
+ * @param {'priority' | 'status' | 'alphabetical'} [criteria='priority']
+ * @returns {TaskItem[]}
+ */
+export function sortTasks(tasks?: TaskItem[], criteria?: "priority" | "status" | "alphabetical"): TaskItem[];
+/**
+ * Determine release status ('wip' | 'closed' | 'unknown')
+ * @param {object} params
+ * @returns {'wip' | 'closed' | 'unknown'}
+ */
+export function determineReleaseStatus({ fmStatus, hasSpec, hasTest, tasks, userStr, metrics }?: object): "wip" | "closed" | "unknown";
+export type TaskItem = {
+    /**
+     * - Task title or description
+     */
+    content: string;
+    /**
+     * - todo | InProgress | Done
+     */
+    status: string;
+    /**
+     * - Task slug / identifier
+     */
+    slug: string;
+    /**
+     * - Numeric priority
+     */
+    priority?: "0" | "1" | "2" | "3" | undefined;
+};

package/types/domain/Dashboard/index.d.ts

@@ -0,0 +1,3 @@
+export { DashboardModel } from "./DashboardModel.js";
+export { parseFrontmatter, extractTasks, calculateDaysRemaining, parseUserMetrics, normalizePriority, resolvePriority, sortTasks, determineReleaseStatus } from "./ReleaseParser.js";
+export { parseSemver, compareSemverDesc, versionToPath, documentExists, loadReleaseDoc, discoverReleases } from "./ReleaseDiscovery.js";

package/types/domain/DepsCommand.d.ts

@@ -16,7 +16,9 @@ export default class DepsCommand extends ModelAsApp {
      * @param {Partial<import('@nan0web/ui').ModelAsAppOptions>} [options]
      */
     constructor(data?: Partial<DepsCommand>, options?: Partial<import("@nan0web/ui").ModelAsAppOptions>);
-    /** @type {boolean} Apply fixes automatically */ fix: boolean;
-    /** @type {boolean} Update packages to the latest available versions */ latest: boolean;
+    /** @type {boolean} Apply fixes automatically */
+    fix: boolean;
+    /** @type {boolean} Update packages to the latest available versions */
+    latest: boolean;
 }
 import { ModelAsApp } from '@nan0web/ui';

package/types/domain/InitCommand.d.ts

@@ -13,6 +13,7 @@ export default class InitCommand extends ModelAsApp {
      * @param {Partial<import('@nan0web/ui').ModelAsAppOptions>} [options]
      */
     constructor(data?: Partial<InitCommand>, options?: Partial<import("@nan0web/ui").ModelAsAppOptions>);
-    /** @type {string} Release version */ version: string;
+    /** @type {string} Release version */
+    version: string;
 }
 import { ModelAsApp } from '@nan0web/ui';

package/types/domain/ListCommand.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ListCommand - ModelAsApp Subcommand to list all available releases in chronological order.
+ */
+export default class ListCommand extends ModelAsApp {
+    static alias: string;
+    static UI: {
+        title: string;
+        help: string;
+        noReleases: string;
+    };
+    /**
+     * @param {Partial<ListCommand>} [data]
+     * @param {import('@nan0web/types').ModelOptions} [options]
+     */
+    constructor(data?: Partial<ListCommand>, options?: import("@nan0web/types").ModelOptions);
+    run(): AsyncGenerator<import("@nan0web/ui/src/core/Intent.js").ShowIntent, import("@nan0web/ui/src/core/Intent.js").ResultIntent, unknown>;
+}
+import { ModelAsApp } from '@nan0web/ui';

package/types/domain/PreviewCommand.d.ts

@@ -0,0 +1,6 @@
+/**
+ * PreviewCommand - ModelAsApp Subcommand to generate, serve and preview PM-as-Code Web Dashboard.
+ */
+export default class PreviewCommand extends WebCommand {
+}
+import WebCommand from './WebCommand.js';

package/types/domain/PublishCommand.d.ts

@@ -20,8 +20,11 @@ export default class PublishCommand extends ModelAsApp {
      * @param {Partial<import('@nan0web/ui').ModelAsAppOptions>} [options]
      */
     constructor(data?: Partial<PublishCommand>, options?: Partial<import("@nan0web/ui").ModelAsAppOptions>);
-    /** @type {boolean} Bump major version */ major: boolean;
-    /** @type {boolean} Bump minor version */ minor: boolean;
-    /** @type {boolean} Bump patch version */ patch: boolean;
+    /** @type {boolean} Bump major version */
+    major: boolean;
+    /** @type {boolean} Bump minor version */
+    minor: boolean;
+    /** @type {boolean} Bump patch version */
+    patch: boolean;
 }
 import { ModelAsApp } from '@nan0web/ui';

package/types/domain/Registry/Registry.story.d.ts

@@ -0,0 +1 @@
+export {};

package/types/domain/Registry/RegistryModel.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @typedef {Object} ProjectEntry
+ * @property {string} path - Project relative or absolute path
+ * @property {string} name - Package name from package.json or folder basename
+ * @property {string} version - Package version from package.json
+ */
+/**
+ * RegistryModel - PM-as-Code Project Registry manager.
+ * Reads project paths from releases.txt and discovers package metadata.
+ */
+export class RegistryModel extends Model {
+    static filePath: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static projects: {
+        help: string;
+        default: () => never[];
+        type: string;
+    };
+    static UI: {
+        fileNotFound: string;
+        loadingProjects: string;
+        projectsLoaded: string;
+    };
+    /**
+     * Parse raw content of releases.txt into array of clean paths
+     * @param {string} content
+     * @returns {string[]}
+     */
+    static parsePaths(content?: string): string[];
+    /**
+     * @param {Partial<RegistryModel>} [data]
+     * @param {import('@nan0web/types').ModelOptions} [options]
+     */
+    constructor(data?: Partial<RegistryModel>, options?: import("@nan0web/types").ModelOptions);
+    /** @type {string} Path to registry file */ filePath: string;
+    /** @type {ProjectEntry[]} List of registered projects */ projects: ProjectEntry[];
+    /**
+     * Load project entries from registry file using injected DB instance
+     * @returns {Promise<ProjectEntry[]>}
+     */
+    loadProjects(): Promise<ProjectEntry[]>;
+}
+export default RegistryModel;
+export type ProjectEntry = {
+    /**
+     * - Project relative or absolute path
+     */
+    path: string;
+    /**
+     * - Package name from package.json or folder basename
+     */
+    name: string;
+    /**
+     * - Package version from package.json
+     */
+    version: string;
+};
+import { Model } from '@nan0web/types';

package/types/domain/ServeCommand.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ServeCommand - Universal ModelAsApp for data or release catalogs.
+ *
+ * Generates HTML content from README.md and release templates using $db and Markdown.
+ * Pure OLMUI model: does not start HTTP server, does not call node:fs or child_process.
+ *
+ * Usage:
+ *   pnpm exec serve releases/  # Runs via CLI bootstrap
+ */
+export default class ServeCommand extends ModelAsApp {
+    static alias: string;
+    static UI: {
+        title: string;
+        help: string;
+        serving: string;
+        dirNotFound: string;
+    };
+    static dir: {
+        help: string;
+        positional: boolean;
+        type: string;
+        default: string;
+    };
+    static port: {
+        help: string;
+        default: number;
+        type: string;
+        alias: string;
+    };
+    static open: {
+        help: string;
+        default: boolean;
+        type: string;
+    };
+    /**
+     * @param {Partial<ServeCommand>} [data]
+     * @param {import('@nan0web/types').ModelOptions} [options]
+     */
+    constructor(data?: Partial<ServeCommand>, options?: import("@nan0web/types").ModelOptions);
+    /** @type {string} */
+    dir: string;
+    /** @type {number} */
+    port: number;
+    /** @type {boolean} */
+    open: boolean;
+    /**
+     * Convert markdown string to HTML using @nan0web/markdown
+     * @param {string} mdRaw
+     * @returns {string}
+     */
+    renderMarkdownToHtml(mdRaw: string): string;
+    /**
+     * Render HTML content for the target directory
+     * @returns {Promise<string>}
+     */
+    renderHtml(): Promise<string>;
+    run(): AsyncGenerator<import("@nan0web/ui/src/core/Intent.js").ShowIntent, import("@nan0web/ui/src/core/Intent.js").ResultIntent, unknown>;
+}
+import { ModelAsApp } from '@nan0web/ui';

package/types/domain/ServeCommand.story.d.ts

@@ -0,0 +1 @@
+export {};

package/types/domain/SpecCommand.d.ts

@@ -12,6 +12,7 @@ export default class SpecCommand extends ModelAsApp {
      * @param {Partial<import('@nan0web/ui').ModelAsAppOptions>} [options]
      */
     constructor(data?: Partial<SpecCommand>, options?: Partial<import("@nan0web/ui").ModelAsAppOptions>);
-    /** @type {string} Release version filter */ version: string;
+    /** @type {string} Release version filter */
+    version: string;
 }
 import { ModelAsApp } from '@nan0web/ui';

package/types/domain/StatusCommand.d.ts

@@ -1,7 +1,46 @@
+/**
+ * StatusCommand - ModelAsApp Subcommand to display PM-as-Code dashboard and project inspector.
+ */
 export default class StatusCommand extends ModelAsApp {
+    static alias: string;
     static UI: {
         title: string;
         help: string;
+        header: string;
+        summaryHeader: string;
+        summaryRow1: string;
+        summaryRow2: string;
+        noProjects: string;
     };
+    static registryFile: {
+        help: string;
+        default: string;
+        type: string;
+        alias: string;
+    };
+    static target: {
+        help: string;
+        default: string;
+        positional: boolean;
+        type: string;
+    };
+    static sort: {
+        help: string;
+        default: string;
+        type: string;
+        alias: string;
+    };
+    /**
+     * @param {Partial<StatusCommand>} [data]
+     * @param {import('@nan0web/types').ModelOptions} [options]
+     */
+    constructor(data?: Partial<StatusCommand>, options?: import("@nan0web/types").ModelOptions);
+    /** @type {string} */ registryFile: string;
+    /** @type {string} */ target: string;
+    /** @type {string} */ sort: string;
+    /**
+     * @returns {AsyncGenerator<import('@nan0web/ui').Intent, any, any>}
+     */
+    run(): AsyncGenerator<import("@nan0web/ui").Intent, any, any>;
 }
 import { ModelAsApp } from '@nan0web/ui';