@therocketcode/gsd-core 1.4.0

package/gsd-core/bin/lib/workstream-inventory-builder.cjs

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Workstream Inventory Builder — pure projection from pre-collected
+ * filesystem data to typed WorkstreamInventory. No I/O. No async.
+ *
+ * ADR-457 build-at-publish: the hand-written
+ * bin/lib/workstream-inventory-builder.cjs collapsed to a TypeScript source
+ * of truth. Behaviour is preserved byte-for-behaviour from the prior
+ * hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCompletedInventory = isCompletedInventory;
+exports.buildWorkstreamInventory = buildWorkstreamInventory;
+const node_path_1 = __importDefault(require("node:path"));
+// Internal helpers
+function toPosixPath(p) {
+    return p.split('\\').join('/');
+}
+function isCompletedInventory(status) {
+    const s = (typeof status === 'string'
+        ? status
+        : typeof status === 'number' || typeof status === 'boolean'
+            ? String(status)
+            : '').trim().toLowerCase();
+    return /\bmilestone\s+complete\b/.test(s) || /\barchived\b/.test(s);
+}
+function buildWorkstreamInventory(inputs) {
+    const { name, projectDir, workstreamDir, phaseDirNames, activeWorkstreamName, phaseFilesCounts, roadmapPhaseCount, stateProjection, filesExist, } = inputs;
+    // Index counts by directory for O(1) lookup during sort/iteration
+    const countsMap = new Map();
+    for (const entry of phaseFilesCounts) {
+        countsMap.set(entry.directory, { planCount: entry.planCount, summaryCount: entry.summaryCount });
+    }
+    const phases = [];
+    let completedPhases = 0;
+    let totalPlans = 0;
+    let completedPlans = 0;
+    for (const dir of [...phaseDirNames].sort()) {
+        const counts = countsMap.get(dir) ?? { planCount: 0, summaryCount: 0 };
+        const status = counts.summaryCount >= counts.planCount && counts.planCount > 0
+            ? 'complete'
+            : counts.planCount > 0
+                ? 'in_progress'
+                : 'pending';
+        totalPlans += counts.planCount;
+        completedPlans += Math.min(counts.summaryCount, counts.planCount);
+        if (status === 'complete')
+            completedPhases++;
+        phases.push({
+            directory: dir,
+            status,
+            plan_count: counts.planCount,
+            summary_count: counts.summaryCount,
+        });
+    }
+    return {
+        name,
+        path: toPosixPath(node_path_1.default.relative(projectDir, workstreamDir)),
+        active: name === activeWorkstreamName,
+        files: {
+            roadmap: filesExist.roadmap,
+            state: filesExist.state,
+            requirements: filesExist.requirements,
+        },
+        status: stateProjection.status,
+        current_phase: stateProjection.current_phase,
+        last_activity: stateProjection.last_activity,
+        phases,
+        phase_count: phases.length,
+        completed_phases: completedPhases,
+        roadmap_phase_count: roadmapPhaseCount,
+        total_plans: totalPlans,
+        completed_plans: completedPlans,
+        progress_percent: roadmapPhaseCount > 0
+            ? Math.min(100, Math.round((completedPhases / roadmapPhaseCount) * 100))
+            : 0,
+    };
+}

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * Workstream Inventory Module
+ *
+ * Owns discovery and read-only projection of .planning/workstreams/* state.
+ * Command handlers should render outputs from this inventory instead of
+ * rescanning workstream directories directly.
+ *
+ * Pure projection logic lives in workstream-inventory-builder.cts.
+ * This module handles I/O orchestration only.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/workstream-inventory.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { readSubdirectories } = core;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planScan = require("./plan-scan.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningPaths, planningRoot, getActiveWorkstream } = planningWorkspace;
+const state_document_cjs_1 = require("./state-document.cjs");
+const workstream_inventory_builder_cjs_1 = require("./workstream-inventory-builder.cjs");
+// ─── Implementation ───────────────────────────────────────────────────────────
+function workstreamsRoot(cwd) {
+    return node_path_1.default.join(planningRoot(cwd), 'workstreams');
+}
+function countRoadmapPhases(roadmapPath, fallbackCount) {
+    try {
+        const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        const matches = roadmapContent.match(/^#{2,4}\s+Phase\s+[\w][\w.-]*/gm);
+        return matches ? matches.length : fallbackCount;
+    }
+    catch {
+        return fallbackCount;
+    }
+}
+function countPhaseFiles(phaseDir) {
+    const scan = planScan(phaseDir);
+    return { planCount: scan.planCount, summaryCount: scan.summaryCount };
+}
+function readStateProjection(statePath) {
+    try {
+        const stateContent = node_fs_1.default.readFileSync(statePath, 'utf-8');
+        return {
+            status: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Status') || 'unknown',
+            current_phase: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Current Phase'),
+            last_activity: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Last Activity'),
+        };
+    }
+    catch {
+        return {
+            status: 'unknown',
+            current_phase: null,
+            last_activity: null,
+        };
+    }
+}
+function sortWorkstreamInventories(inventories, activeWorkstreamName) {
+    return [...inventories].sort((a, b) => {
+        const aActive = a.name === activeWorkstreamName ? 1 : 0;
+        const bActive = b.name === activeWorkstreamName ? 1 : 0;
+        if (aActive !== bActive) {
+            return bActive - aActive;
+        }
+        return a.name.localeCompare(b.name);
+    });
+}
+function inspectWorkstream(cwd, name, options = {}) {
+    const wsDir = node_path_1.default.join(workstreamsRoot(cwd), name);
+    if (!node_fs_1.default.existsSync(wsDir))
+        return null;
+    const activeWorkstreamName = options.active === undefined ? getActiveWorkstream(cwd) : options.active;
+    const p = planningPaths(cwd, name);
+    const phaseDirNames = readSubdirectories(p.phases);
+    // Collect per-phase file counts
+    const phaseFilesCounts = phaseDirNames.map(dir => {
+        const counts = countPhaseFiles(node_path_1.default.join(p.phases, dir));
+        return { directory: dir, planCount: counts.planCount, summaryCount: counts.summaryCount };
+    });
+    return (0, workstream_inventory_builder_cjs_1.buildWorkstreamInventory)({
+        name,
+        projectDir: cwd,
+        workstreamDir: wsDir,
+        phaseDirNames,
+        activeWorkstreamName: activeWorkstreamName ?? '',
+        phaseFilesCounts,
+        roadmapPhaseCount: countRoadmapPhases(p.roadmap, phaseDirNames.length),
+        stateProjection: readStateProjection(p.state),
+        filesExist: {
+            roadmap: node_fs_1.default.existsSync(p.roadmap),
+            state: node_fs_1.default.existsSync(p.state),
+            requirements: node_fs_1.default.existsSync(p.requirements),
+        },
+    });
+}
+function listWorkstreamInventories(cwd) {
+    const wsRoot = workstreamsRoot(cwd);
+    if (!node_fs_1.default.existsSync(wsRoot)) {
+        return {
+            mode: 'flat',
+            active: null,
+            workstreams: [],
+            count: 0,
+            message: 'No workstreams — operating in flat mode',
+        };
+    }
+    const active = getActiveWorkstream(cwd);
+    const entries = node_fs_1.default.readdirSync(wsRoot, { withFileTypes: true });
+    const workstreams = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const inventory = inspectWorkstream(cwd, entry.name, { active });
+        if (inventory)
+            workstreams.push(inventory);
+    }
+    const ordered = sortWorkstreamInventories(workstreams, active);
+    return {
+        mode: 'workstream',
+        active,
+        workstreams: ordered,
+        count: ordered.length,
+    };
+}
+function getOtherActiveWorkstreamInventories(cwd, excludeWs) {
+    return listWorkstreamInventories(cwd).workstreams
+        .filter(inventory => inventory.name !== excludeWs)
+        .filter(inventory => !(0, workstream_inventory_builder_cjs_1.isCompletedInventory)(inventory.status));
+}
+module.exports = {
+    countPhaseFiles,
+    countRoadmapPhases,
+    getOtherActiveWorkstreamInventories,
+    inspectWorkstream,
+    isCompletedInventory: workstream_inventory_builder_cjs_1.isCompletedInventory,
+    listWorkstreamInventories,
+    sortWorkstreamInventories,
+    workstreamsRoot,
+};

package/gsd-core/bin/lib/workstream-name-policy.cjs

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Canonical workstream name validation and slug normalization
+ * (ADR-457 build-at-publish: the hand-written bin/lib/workstream-name-policy.cjs
+ * collapsed to a TypeScript source of truth). Behaviour is preserved
+ * byte-for-behaviour from the prior hand-written .cjs; only types are added.
+ *
+ * Used by active-workstream-store.cjs, planning-workspace.cjs, workstream.cjs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = void 0;
+exports.normalizeWorkstreamNameInput = normalizeWorkstreamNameInput;
+exports.hasInvalidPathSegment = hasInvalidPathSegment;
+exports.validateActiveWorkstreamName = validateActiveWorkstreamName;
+exports.validateWorkstreamName = validateWorkstreamName;
+exports.toWorkstreamSlug = toWorkstreamSlug;
+exports.isValidActiveWorkstreamName = isValidActiveWorkstreamName;
+exports.assertValidActiveWorkstreamName = assertValidActiveWorkstreamName;
+exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = 'Invalid workstream name: must be alphanumeric, hyphens, underscores, or dots';
+const ACTIVE_WORKSTREAM_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+function normalizeWorkstreamNameInput(name) {
+    const value = String(name ?? '').trim();
+    return value || null;
+}
+/**
+ * Returns true when `name` contains a path separator, a bare dot, or a
+ * dot-dot sequence — any of which would make the name unsafe for use as a
+ * filesystem path segment.
+ */
+function hasInvalidPathSegment(name) {
+    const value = String(name ?? '');
+    return /[/\\]/.test(value) || value === '.' || value === '..' || value.includes('..');
+}
+function validateActiveWorkstreamName(name) {
+    const value = normalizeWorkstreamNameInput(name);
+    if (!value) {
+        return {
+            ok: false,
+            reason: 'empty',
+            value: null,
+        };
+    }
+    if (hasInvalidPathSegment(value) || !ACTIVE_WORKSTREAM_RE.test(value)) {
+        return {
+            ok: false,
+            reason: 'invalid',
+            value,
+        };
+    }
+    return {
+        ok: true,
+        reason: null,
+        value,
+    };
+}
+/**
+ * Validate a workstream name.
+ * Allowed: alphanumeric, hyphens, underscores, dots.
+ * Disallowed: empty, spaces, slashes, special chars, path traversal.
+ *
+ * Alias for isValidActiveWorkstreamName; provided for SDK-layer callers.
+ */
+function validateWorkstreamName(name) {
+    return isValidActiveWorkstreamName(name);
+}
+/**
+ * Convert a display name to a URL/filesystem-safe workstream slug.
+ * Lowercases, collapses non-alphanumeric runs to hyphens, strips leading/trailing hyphens.
+ */
+function toWorkstreamSlug(name) {
+    return String(name ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Returns true when `name` is a valid active workstream name:
+ * - Must start with alphanumeric
+ * - May contain alphanumeric, dots, underscores, hyphens
+ * - Must not contain path traversal sequences (..)
+ */
+function isValidActiveWorkstreamName(name) {
+    return validateActiveWorkstreamName(name).ok;
+}
+function assertValidActiveWorkstreamName(name, errorMessage = exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE) {
+    const validation = validateActiveWorkstreamName(name);
+    if (!validation.ok) {
+        throw new Error(errorMessage);
+    }
+    return validation.value;
+}