@taskforcehq/taskforce 0.3.168

package/dist/utils/planParser.js

@@ -0,0 +1,151 @@
+/**
+ * planParser.ts
+ * Parses a markdown implementation plan into a structured task tree.
+ * Pure function — no I/O, no side effects.
+ */
+// ─── Inference helpers ──────────────────────────────────────────────────────
+function inferType(title) {
+    const l = title.toLowerCase();
+    if (/\b(bug|fix|fixes|fixed|broken|broken|regression|hotfix)\b/.test(l))
+        return 'bug';
+    if (/\b(refactor|refactoring|rewrite|cleanup|clean.?up|reorgani[sz]e)\b/.test(l))
+        return 'refactor';
+    if (/\b(doc|docs|documentation|readme|changelog|comment|comments)\b/.test(l))
+        return 'documentation';
+    if (/\b(chore|setup|set.?up|config|configuration|infra|infrastructure|ci|cd|deploy|migration|upgrade)\b/.test(l))
+        return 'chore';
+    return 'feature';
+}
+function inferPriority(title) {
+    const l = title.toLowerCase();
+    if (/\b(critical|blocker|p0|urgent)\b/.test(l))
+        return 4;
+    if (/\b(high|important|p1)\b/.test(l))
+        return 3;
+    if (/\b(low|minor|nice.?to.?have|p3)\b/.test(l))
+        return 1;
+    return 2;
+}
+function slugify(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '').slice(0, 60);
+}
+function makeKey(title, depth, parentKey = '') {
+    const s = slugify(title);
+    return parentKey ? `${parentKey}:${depth}:${s}` : `${depth}:${s}`;
+}
+function classifyLine(raw) {
+    const h2 = raw.match(/^##\s+(.+)/);
+    if (h2)
+        return { kind: 'h2', text: h2[1].trim() };
+    const h3 = raw.match(/^###\s+(.+)/);
+    if (h3)
+        return { kind: 'h3', text: h3[1].trim() };
+    const h4 = raw.match(/^####\s+(.+)/);
+    if (h4)
+        return { kind: 'h4', text: h4[1].trim() };
+    // List items: -, *, + with optional leading whitespace
+    const li = raw.match(/^(\s*)[-*+]\s+(.+)/);
+    if (li)
+        return { kind: 'listItem', text: li[2].trim(), indent: li[1].length };
+    // Numbered list
+    const oli = raw.match(/^(\s*)\d+[.)]\s+(.+)/);
+    if (oli)
+        return { kind: 'listItem', text: oli[2].trim(), indent: oli[1].length };
+    return { kind: 'other', text: raw.trim() };
+}
+// ─── Main parser ─────────────────────────────────────────────────────────────
+export function parsePlan(markdown) {
+    const lines = markdown.split('\n');
+    const roots = [];
+    let currentH2 = null;
+    let currentH3 = null;
+    // Track context description lines (plain text before first bullet/heading belongs to current node)
+    let descBuffer = [];
+    function flushDesc(node) {
+        if (node && descBuffer.length > 0) {
+            const candidate = descBuffer.join(' ').trim();
+            if (candidate && !node.description)
+                node.description = candidate;
+        }
+        descBuffer = [];
+    }
+    function makeNode(title, depth, parentKey = '') {
+        return {
+            idempotencyKey: makeKey(title, depth, parentKey),
+            title,
+            description: '',
+            type: inferType(title),
+            priority: inferPriority(title),
+            depth,
+            children: [],
+            selected: true,
+        };
+    }
+    for (const rawLine of lines) {
+        const line = classifyLine(rawLine);
+        if (line.kind === 'h2') {
+            flushDesc(currentH3 ?? currentH2);
+            currentH3 = null;
+            currentH2 = makeNode(line.text, 0);
+            roots.push(currentH2);
+            continue;
+        }
+        if (line.kind === 'h3') {
+            flushDesc(currentH3 ?? currentH2);
+            currentH3 = makeNode(line.text, 1, currentH2?.idempotencyKey);
+            if (currentH2) {
+                currentH2.children.push(currentH3);
+            }
+            else {
+                // H3 without parent H2 — treat as root
+                roots.push(currentH3);
+            }
+            continue;
+        }
+        if (line.kind === 'h4') {
+            // H4s treated as list-item equivalents under H3
+            flushDesc(currentH3 ?? currentH2);
+            const parent = currentH3 ?? currentH2;
+            if (parent) {
+                const node = makeNode(line.text, parent.depth + 1, parent.idempotencyKey);
+                parent.children.push(node);
+            }
+            continue;
+        }
+        if (line.kind === 'listItem') {
+            flushDesc(currentH3 ?? currentH2);
+            const parent = currentH3 ?? currentH2;
+            if (parent) {
+                const depth = parent.depth + 1;
+                const node = makeNode(line.text, depth, parent.idempotencyKey);
+                parent.children.push(node);
+            }
+            continue;
+        }
+        // Plain text — could be description
+        if (line.kind === 'other' && line.text && !line.text.startsWith('#')) {
+            // Strip markdown formatting and horizontal rules
+            const clean = line.text.replace(/^[-*_]{3,}$/, '').trim();
+            if (clean)
+                descBuffer.push(clean);
+        }
+    }
+    flushDesc(currentH3 ?? currentH2);
+    // Filter out nodes that are purely structural (e.g. document title H2 with no list children)
+    // Keep only nodes that have a actionable title (not just "Goal", "Overview", etc.)
+    return roots.filter(r => r.title.length > 0);
+}
+// Flatten a parsed tree to a list (breadth-first), only selected nodes
+export function flattenSelected(tasks) {
+    const result = [];
+    function walk(nodes) {
+        for (const node of nodes) {
+            if (node.selected) {
+                result.push(node);
+                walk(node.children);
+            }
+        }
+    }
+    walk(tasks);
+    return result;
+}

package/dist/utils/taskDragZones.d.ts

@@ -0,0 +1,8 @@
+type Rect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export declare const isDropInCenterZone: (overRect: Rect, activeRect: Rect, centerZoneRatio?: number) => boolean;
+export {};

package/dist/utils/taskDragZones.js

@@ -0,0 +1,14 @@
+export const isDropInCenterZone = (overRect, activeRect, centerZoneRatio = 0.56) => {
+    const zoneWidth = overRect.width * centerZoneRatio;
+    const zoneHeight = overRect.height * centerZoneRatio;
+    const zoneLeft = overRect.left + (overRect.width - zoneWidth) / 2;
+    const zoneTop = overRect.top + (overRect.height - zoneHeight) / 2;
+    const zoneRight = zoneLeft + zoneWidth;
+    const zoneBottom = zoneTop + zoneHeight;
+    const activeCenterX = activeRect.left + activeRect.width / 2;
+    const activeCenterY = activeRect.top + activeRect.height / 2;
+    return (activeCenterX >= zoneLeft &&
+        activeCenterX <= zoneRight &&
+        activeCenterY >= zoneTop &&
+        activeCenterY <= zoneBottom);
+};

package/dist/utils/taskDragZones.test.d.ts

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

package/dist/utils/taskDragZones.test.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { isDropInCenterZone } from './taskDragZones';
+describe('taskDragZones', () => {
+    it('returns true when dragged card center is inside the target center zone', () => {
+        const overRect = { left: 0, top: 0, width: 200, height: 120 };
+        const activeRect = { left: 80, top: 45, width: 40, height: 30 };
+        expect(isDropInCenterZone(overRect, activeRect)).toBe(true);
+    });
+    it('returns false when dragged card center is outside the target center zone', () => {
+        const overRect = { left: 0, top: 0, width: 200, height: 120 };
+        const activeRect = { left: 5, top: 5, width: 30, height: 30 };
+        expect(isDropInCenterZone(overRect, activeRect)).toBe(false);
+    });
+});

package/dist/utils/taskHierarchy.d.ts

@@ -0,0 +1,4 @@
+import type { TaskItem } from '../types';
+export declare function buildHierarchyDepthMap(tasks: TaskItem[]): Map<string, number>;
+export declare function getMaxHierarchyDepth(tasks: TaskItem[]): number;
+export declare function collectSubtreeTaskIds(tasks: TaskItem[], rootId: string): Set<string>;

package/dist/utils/taskHierarchy.js

@@ -0,0 +1,69 @@
+export function buildHierarchyDepthMap(tasks) {
+    const byId = new Map();
+    tasks.forEach((task) => byId.set(task.id, task));
+    const depthMemo = new Map();
+    const resolveDepth = (taskId, visiting) => {
+        const cached = depthMemo.get(taskId);
+        if (typeof cached === 'number')
+            return cached;
+        const task = byId.get(taskId);
+        if (!task)
+            return 0;
+        const parentId = task.parentTaskId || null;
+        if (!parentId || !byId.has(parentId)) {
+            depthMemo.set(taskId, 0);
+            return 0;
+        }
+        if (visiting.has(taskId) || visiting.has(parentId)) {
+            // Cycle fallback: treat node as root-level for safe rendering.
+            depthMemo.set(taskId, 0);
+            return 0;
+        }
+        visiting.add(taskId);
+        const depth = resolveDepth(parentId, visiting) + 1;
+        visiting.delete(taskId);
+        depthMemo.set(taskId, depth);
+        return depth;
+    };
+    tasks.forEach((task) => {
+        resolveDepth(task.id, new Set());
+    });
+    return depthMemo;
+}
+export function getMaxHierarchyDepth(tasks) {
+    const depthMap = buildHierarchyDepthMap(tasks);
+    let maxDepth = 0;
+    depthMap.forEach((depth) => {
+        if (depth > maxDepth)
+            maxDepth = depth;
+    });
+    return maxDepth;
+}
+export function collectSubtreeTaskIds(tasks, rootId) {
+    if (!rootId)
+        return new Set();
+    const childrenByParent = new Map();
+    tasks.forEach((task) => {
+        if (!task.parentTaskId)
+            return;
+        const list = childrenByParent.get(task.parentTaskId) || [];
+        list.push(task.id);
+        childrenByParent.set(task.parentTaskId, list);
+    });
+    const result = new Set();
+    const visited = new Set();
+    const stack = [rootId];
+    while (stack.length > 0) {
+        const currentId = stack.pop();
+        if (visited.has(currentId))
+            continue;
+        visited.add(currentId);
+        result.add(currentId);
+        const children = childrenByParent.get(currentId) || [];
+        children.forEach((childId) => {
+            if (!visited.has(childId))
+                stack.push(childId);
+        });
+    }
+    return result;
+}

package/dist/utils/taskHierarchy.test.d.ts

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

package/dist/utils/taskHierarchy.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { collectSubtreeTaskIds } from './taskHierarchy';
+const task = (overrides) => ({
+    id: 'task-default',
+    title: 'Task',
+    description: null,
+    category: 'general',
+    type: 'feature',
+    priority: 2,
+    status: 'task',
+    createdAt: '2026-02-16T00:00:00.000Z',
+    ...overrides
+});
+describe('collectSubtreeTaskIds', () => {
+    it('collects selected parent and all descendants recursively', () => {
+        const root = task({ id: 'task-root' });
+        const childA = task({ id: 'task-a', parentTaskId: root.id });
+        const childB = task({ id: 'task-b', parentTaskId: root.id });
+        const grandchild = task({ id: 'task-c', parentTaskId: childA.id });
+        const unrelated = task({ id: 'task-z' });
+        const result = collectSubtreeTaskIds([root, childA, childB, grandchild, unrelated], root.id);
+        expect(result.has(root.id)).toBe(true);
+        expect(result.has(childA.id)).toBe(true);
+        expect(result.has(childB.id)).toBe(true);
+        expect(result.has(grandchild.id)).toBe(true);
+        expect(result.has(unrelated.id)).toBe(false);
+    });
+    it('is cycle-safe when descendant links create a loop', () => {
+        const a = task({ id: 'task-a', parentTaskId: 'task-c' });
+        const b = task({ id: 'task-b', parentTaskId: a.id });
+        const c = task({ id: 'task-c', parentTaskId: b.id });
+        const result = collectSubtreeTaskIds([a, b, c], a.id);
+        expect(result.has(a.id)).toBe(true);
+        expect(result.has(b.id)).toBe(true);
+        expect(result.has(c.id)).toBe(true);
+        expect(result.size).toBe(3);
+    });
+});

package/dist/utils/taskParenting.d.ts

@@ -0,0 +1,3 @@
+import type { TaskItem } from '../types';
+export declare const shouldPromptReparent: (currentParentId?: string | null, nextParentId?: string | null) => boolean;
+export declare const wouldCreateParentCycle: (childId: string, nextParentId: string | null | undefined, tasks: TaskItem[]) => boolean;

package/dist/utils/taskParenting.js

@@ -0,0 +1,24 @@
+export const shouldPromptReparent = (currentParentId, nextParentId) => {
+    return Boolean(currentParentId && nextParentId && currentParentId !== nextParentId);
+};
+export const wouldCreateParentCycle = (childId, nextParentId, tasks) => {
+    if (!nextParentId)
+        return false;
+    if (childId === nextParentId)
+        return true;
+    const parentById = new Map();
+    for (const task of tasks) {
+        parentById.set(task.id, task.parentTaskId);
+    }
+    let cursor = nextParentId;
+    const visited = new Set();
+    while (cursor) {
+        if (cursor === childId)
+            return true;
+        if (visited.has(cursor))
+            return true;
+        visited.add(cursor);
+        cursor = parentById.get(cursor) || null;
+    }
+    return false;
+};

package/dist/utils/taskParenting.test.d.ts

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

package/dist/utils/taskParenting.test.js

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import { shouldPromptReparent, wouldCreateParentCycle } from './taskParenting';
+describe('taskParenting', () => {
+    it('prompts when moving from one parent to a different parent', () => {
+        expect(shouldPromptReparent('task-parent-a', 'task-parent-b')).toBe(true);
+    });
+    it('does not prompt when parent is unchanged or absent', () => {
+        expect(shouldPromptReparent('task-parent-a', 'task-parent-a')).toBe(false);
+        expect(shouldPromptReparent(null, 'task-parent-a')).toBe(false);
+        expect(shouldPromptReparent('task-parent-a', null)).toBe(false);
+    });
+    it('detects parent cycles through ancestor chains', () => {
+        const tasks = [
+            { id: 'task-a', parentTaskId: null },
+            { id: 'task-b', parentTaskId: 'task-a' },
+            { id: 'task-c', parentTaskId: 'task-b' }
+        ];
+        expect(wouldCreateParentCycle('task-a', 'task-c', tasks)).toBe(true);
+        expect(wouldCreateParentCycle('task-c', 'task-a', tasks)).toBe(false);
+    });
+});

package/dist/utils/taskRelations.d.ts

@@ -0,0 +1,6 @@
+import type { TaskItem } from '../types';
+export declare const isTerminalStatus: (status?: TaskItem["status"]) => status is "done" | "cancelled";
+export declare const isTerminalTaskState: (task: TaskItem) => boolean;
+export declare const getActiveDirectChildCount: (parentTaskId: string, tasks: TaskItem[]) => number;
+export declare const hasActiveDirectChildren: (parentTaskId: string, tasks: TaskItem[]) => boolean;
+export declare const sortChildTasksForDisplay: (tasks: TaskItem[]) => TaskItem[];

package/dist/utils/taskRelations.js

@@ -0,0 +1,24 @@
+export const isTerminalStatus = (status) => {
+    return status === 'done' || status === 'cancelled';
+};
+export const isTerminalTaskState = (task) => {
+    return Boolean(task.isArchived) || isTerminalStatus(task.status);
+};
+export const getActiveDirectChildCount = (parentTaskId, tasks) => {
+    return tasks.filter((task) => task.parentTaskId === parentTaskId && !isTerminalTaskState(task)).length;
+};
+export const hasActiveDirectChildren = (parentTaskId, tasks) => {
+    return getActiveDirectChildCount(parentTaskId, tasks) > 0;
+};
+export const sortChildTasksForDisplay = (tasks) => {
+    return [...tasks].sort((a, b) => {
+        const archivedDelta = Number(Boolean(a.isArchived)) - Number(Boolean(b.isArchived));
+        if (archivedDelta !== 0)
+            return archivedDelta;
+        const aOrder = typeof a.childDisplayOrder === 'number' ? a.childDisplayOrder : Number.POSITIVE_INFINITY;
+        const bOrder = typeof b.childDisplayOrder === 'number' ? b.childDisplayOrder : Number.POSITIVE_INFINITY;
+        if (aOrder !== bOrder)
+            return aOrder - bOrder;
+        return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+    });
+};

package/dist/utils/taskRelations.test.d.ts

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

package/dist/utils/taskRelations.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { getActiveDirectChildCount, hasActiveDirectChildren, isTerminalTaskState } from './taskRelations';
+const makeTask = (overrides) => ({
+    id: 'task-default',
+    title: 'Task',
+    description: null,
+    category: 'general',
+    type: 'feature',
+    priority: 2,
+    status: 'task',
+    createdAt: new Date().toISOString(),
+    ...overrides
+});
+describe('taskRelations', () => {
+    it('treats archived tasks as terminal state', () => {
+        const archived = makeTask({
+            id: 'task-archived',
+            status: 'task',
+            isArchived: true
+        });
+        expect(isTerminalTaskState(archived)).toBe(true);
+    });
+    it('does not count archived child tasks as active direct children', () => {
+        const tasks = [
+            makeTask({ id: 'parent', title: 'Parent' }),
+            makeTask({ id: 'active-child', parentTaskId: 'parent', status: 'in-progress' }),
+            makeTask({ id: 'archived-child', parentTaskId: 'parent', status: 'task', isArchived: true }),
+            makeTask({ id: 'done-child', parentTaskId: 'parent', status: 'done' }),
+            makeTask({ id: 'cancelled-child', parentTaskId: 'parent', status: 'cancelled' })
+        ];
+        expect(getActiveDirectChildCount('parent', tasks)).toBe(1);
+        expect(hasActiveDirectChildren('parent', tasks)).toBe(true);
+    });
+});

package/dist/utils/taskUtils.d.ts

@@ -0,0 +1,2 @@
+export declare const getIconForType: (type: string, size?: number) => import("react/jsx-runtime").JSX.Element;
+export declare const renderHighlighted: (text: string | null | undefined, query: string) => string | import("react/jsx-runtime").JSX.Element | null;

package/dist/utils/taskUtils.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import * as Icons from 'lucide-react';
+import { TypeMeta } from './constants';
+import styles from '../Taskforce.module.css';
+export const getIconForType = (type, size = 10) => {
+    const meta = TypeMeta[type?.toLowerCase()] || { icon: 'FileCode', color: 'indigo-500' };
+    const IconComp = Icons[meta.icon] || Icons.FileCode;
+    return _jsx(IconComp, { size: size });
+};
+export const renderHighlighted = (text, query) => {
+    if (!text)
+        return null;
+    if (!query.trim())
+        return text;
+    const escapedQuery = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const parts = text.split(new RegExp(`(${escapedQuery})`, 'gi'));
+    return (_jsx(_Fragment, { children: parts.map((part, i) => part.toLowerCase() === query.toLowerCase()
+            ? _jsx("mark", { className: styles.highlight, children: part }, i)
+            : part) }));
+};

package/dist/utils/taskforceApiClient.d.ts

@@ -0,0 +1,7 @@
+export declare function resolveTaskforceApiUrl(path: string, apiBaseUrl?: string): string;
+/**
+ * Fetches Taskforce API endpoints with a resilient fallback:
+ * if a configured apiBaseUrl request fails at the network layer,
+ * retry once against same-origin path.
+ */
+export declare function fetchTaskforceApi(path: string, init?: RequestInit, apiBaseUrl?: string): Promise<Response>;

package/dist/utils/taskforceApiClient.js

@@ -0,0 +1,42 @@
+function normalizeApiBaseUrl(apiBaseUrl) {
+    return typeof apiBaseUrl === 'string' ? apiBaseUrl.trim().replace(/\/+$/, '') : '';
+}
+export function resolveTaskforceApiUrl(path, apiBaseUrl) {
+    if (!path.startsWith('/'))
+        return path;
+    const base = normalizeApiBaseUrl(apiBaseUrl);
+    if (!base)
+        return path;
+    return `${base}${path}`;
+}
+/**
+ * Fetches Taskforce API endpoints with a resilient fallback:
+ * if a configured apiBaseUrl request fails at the network layer,
+ * retry once against same-origin path.
+ */
+export async function fetchTaskforceApi(path, init, apiBaseUrl) {
+    const primaryUrl = resolveTaskforceApiUrl(path, apiBaseUrl);
+    const hasConfiguredBase = normalizeApiBaseUrl(apiBaseUrl).length > 0;
+    try {
+        const primaryResponse = await fetch(primaryUrl, init);
+        const shouldRetryAuthFallback = hasConfiguredBase
+            && primaryUrl !== path
+            && path.startsWith('/api/taskforce/')
+            && (primaryResponse.status === 401 || primaryResponse.status === 403);
+        if (!shouldRetryAuthFallback) {
+            return primaryResponse;
+        }
+        try {
+            return await fetch(path, init);
+        }
+        catch {
+            return primaryResponse;
+        }
+    }
+    catch (primaryError) {
+        if (!hasConfiguredBase || !path.startsWith('/')) {
+            throw primaryError;
+        }
+        return fetch(path, init);
+    }
+}

package/dist/utils/workspaceIdentity.d.ts

@@ -0,0 +1,8 @@
+export declare const RESERVED_WORKSPACE_ID = "default";
+export declare const WORKSPACE_BOOTSTRAP_SCOPE = "bootstrap";
+export declare function generateWorkspaceId(): string;
+export declare function normalizeWorkspaceStorageScope(scopeRaw?: string): string;
+export declare function normalizeWorkspaceStorageScopeLegacy(scopeRaw?: string): string;
+export declare function resolveWorkspaceStorageScopeFromProjectRoot(projectRoot?: string): string;
+export declare function isReservedWorkspaceId(workspaceId: string): boolean;
+export declare function isUsableWorkspaceId(workspaceId: string): boolean;

package/dist/utils/workspaceIdentity.js

@@ -0,0 +1,47 @@
+export const RESERVED_WORKSPACE_ID = 'default';
+export const WORKSPACE_BOOTSTRAP_SCOPE = 'bootstrap';
+function hashScopeSeed(input) {
+    let hash = 2166136261;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+export function generateWorkspaceId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `workspace-${crypto.randomUUID()}`;
+    }
+    return `workspace-${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 14)}`;
+}
+export function normalizeWorkspaceStorageScope(scopeRaw) {
+    const raw = String(scopeRaw || '').trim().toLowerCase();
+    if (!raw)
+        return WORKSPACE_BOOTSTRAP_SCOPE;
+    const compact = raw.replace(/[^a-z0-9._-]/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+    const normalized = compact || 'project';
+    const prefix = normalized.slice(0, 56);
+    return `${prefix}-${hashScopeSeed(raw)}`;
+}
+export function normalizeWorkspaceStorageScopeLegacy(scopeRaw) {
+    const raw = String(scopeRaw || '').trim().toLowerCase();
+    if (!raw)
+        return WORKSPACE_BOOTSTRAP_SCOPE;
+    const compact = raw.replace(/[^a-z0-9._-]/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+    if (!compact)
+        return WORKSPACE_BOOTSTRAP_SCOPE;
+    return compact.slice(0, 96);
+}
+export function resolveWorkspaceStorageScopeFromProjectRoot(projectRoot) {
+    const raw = String(projectRoot || '').trim();
+    if (!raw)
+        return WORKSPACE_BOOTSTRAP_SCOPE;
+    return normalizeWorkspaceStorageScope(raw);
+}
+export function isReservedWorkspaceId(workspaceId) {
+    return String(workspaceId || '').trim().toLowerCase() === RESERVED_WORKSPACE_ID;
+}
+export function isUsableWorkspaceId(workspaceId) {
+    const normalized = String(workspaceId || '').trim();
+    return normalized.length > 0 && !isReservedWorkspaceId(normalized);
+}

package/dist/utils/workspaceIdentity.test.d.ts

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

package/dist/utils/workspaceIdentity.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { RESERVED_WORKSPACE_ID, WORKSPACE_BOOTSTRAP_SCOPE, generateWorkspaceId, isReservedWorkspaceId, isUsableWorkspaceId, normalizeWorkspaceStorageScopeLegacy, normalizeWorkspaceStorageScope, resolveWorkspaceStorageScopeFromProjectRoot } from './workspaceIdentity';
+describe('workspace identity invariants', () => {
+    it('uses bootstrap scope when project root is unavailable', () => {
+        expect(resolveWorkspaceStorageScopeFromProjectRoot('')).toBe(WORKSPACE_BOOTSTRAP_SCOPE);
+        expect(normalizeWorkspaceStorageScope('')).toBe(WORKSPACE_BOOTSTRAP_SCOPE);
+    });
+    it('normalizes project-root-derived scope with stable hash suffix', () => {
+        const scope = resolveWorkspaceStorageScopeFromProjectRoot('/Users/ross/My Project');
+        expect(scope.startsWith('users-ross-my-project-')).toBe(true);
+        expect(scope.length).toBeGreaterThan('users-ross-my-project-'.length);
+    });
+    it('keeps legacy scope normalization for migration fallback', () => {
+        expect(normalizeWorkspaceStorageScopeLegacy('/Users/ross/My Project')).toBe('users-ross-my-project');
+    });
+    it('avoids collisions for similarly normalized path variants', () => {
+        const a = normalizeWorkspaceStorageScope('/Users/ross/Maple Valley Group');
+        const b = normalizeWorkspaceStorageScope('/Users/ross/Maple-Valley-Group');
+        expect(a).not.toBe(b);
+    });
+    it('never treats default as usable workspace id', () => {
+        expect(isReservedWorkspaceId(RESERVED_WORKSPACE_ID)).toBe(true);
+        expect(isReservedWorkspaceId(' Default ')).toBe(true);
+        expect(isUsableWorkspaceId('default')).toBe(false);
+        expect(isUsableWorkspaceId('workspace-123')).toBe(true);
+    });
+    it('generates non-default workspace ids with workspace- prefix', () => {
+        const id = generateWorkspaceId();
+        expect(id.startsWith('workspace-')).toBe(true);
+        expect(id.toLowerCase()).not.toBe(RESERVED_WORKSPACE_ID);
+    });
+});

package/dist/utils/workspaceLifecycle.d.ts

@@ -0,0 +1,26 @@
+export type WorkspaceRuntimeMode = 'local' | 'cloud';
+export type SetupStateStatus = 'present' | 'missing' | 'unreadable';
+export type WorkspaceMode = 'core' | 'operations';
+export interface WorkspaceSetupStateSnapshot {
+    globalSetupState: SetupStateStatus;
+    workspaceSetupState: SetupStateStatus;
+    runtimeMode: WorkspaceRuntimeMode;
+    workspaceId: string;
+    mode: WorkspaceMode;
+    forceSetup: boolean;
+    forceGlobalSetup: boolean;
+    forceWorkspaceSetup: boolean;
+}
+export type WorkspaceLifecyclePhase = 'ready' | 'needs-global-setup' | 'needs-workspace-setup' | 'setup-read-error';
+export interface WorkspaceLifecycleResolution {
+    setupGateActive: boolean;
+    needsGlobalSetup: boolean;
+    needsWorkspaceSetup: boolean;
+    hasSetupReadError: boolean;
+    phase: WorkspaceLifecyclePhase;
+}
+export declare function resolveWorkspaceLifecycleState(input: {
+    setupState: WorkspaceSetupStateSnapshot | null;
+    runtimeMode: WorkspaceRuntimeMode;
+    isAuthenticated: boolean;
+}): WorkspaceLifecycleResolution;