crewly 1.5.22 → 1.6.0

package/dist/backend/backend/src/services/credential/helpers/gemini-cli-workspace.helper.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Gemini CLI Workspace Credential Helper
+ *
+ * Piggybacks on the Google Workspace extension for Gemini CLI
+ * (https://github.com/gemini-cli-extensions/workspace) for Google OAuth
+ * credential acquisition and refresh.
+ *
+ * **Capture** reads the extension's file-storage token file (written when
+ * the user runs the extension with `GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true`)
+ * and imports the tokens into Crewly's own encrypted store.
+ *
+ * **Refresh** POSTs the stored `refresh_token` to the extension's Cloud
+ * Function `/refreshToken` endpoint — no client_secret needed on our side.
+ *
+ * After capture, Crewly owns the tokens; the extension's own state is not
+ * depended on for day-to-day operation.
+ *
+ * @module services/credential/helpers/gemini-cli-workspace.helper
+ */
+import { CredentialHelper, CredentialHelperName, CredentialRegistryEntry, GoogleOAuthPayload } from '../../../types/credential.types.js';
+import { CredentialStoreService } from '../credential-store.service.js';
+/**
+ * Minimal fetch-compatible function shape (for test injection).
+ */
+export type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+/**
+ * Helper configuration — all fields optional; defaults match production.
+ */
+export interface GeminiCliHelperConfig {
+    /** Path to the extension install directory (default: `~/.gemini/extensions/google-workspace`). */
+    extensionPath?: string;
+    /** Cloud Function base URL. */
+    cloudFunctionUrl?: string;
+    /** Path on the cloud function for refresh calls. */
+    refreshPath?: string;
+    /** Client ID to store on the credential (for later refresh identification). */
+    clientId?: string;
+    /** Refresh buffer in ms — refresh if token expires within this window. */
+    expiryBufferMs?: number;
+    /** Fetch implementation (injectable for tests). */
+    fetch?: FetchLike;
+}
+/**
+ * Credential helper that reads tokens from the gemini-cli-workspace extension
+ * and refreshes them via the extension's Cloud Function.
+ */
+export declare class GeminiCliWorkspaceHelper implements CredentialHelper {
+    readonly name: CredentialHelperName;
+    private readonly extensionPath;
+    private readonly cloudFunctionUrl;
+    private readonly refreshPath;
+    private readonly clientId;
+    private readonly expiryBufferMs;
+    private readonly fetchFn;
+    private readonly store;
+    /** Per-credential refresh in-flight promises (serializes concurrent refreshes). */
+    private readonly refreshInFlight;
+    /** Per-credential last refresh attempt timestamp (for cooldown). */
+    private readonly lastRefreshAttempt;
+    constructor(store: CredentialStoreService, config?: GeminiCliHelperConfig);
+    /**
+     * Read the extension's current token file and return its contents as a
+     * `GoogleOAuthPayload` ready to persist in Crewly's store.
+     *
+     * The user must have completed extension login with
+     * `GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true` before calling this.
+     */
+    captureFromFile(): Promise<GoogleOAuthPayload>;
+    /**
+     * Remove the extension's token file. Call after `captureFromFile()` to
+     * prepare for the next account's login (the extension otherwise returns
+     * cached credentials if scopes match, skipping the login prompt).
+     * Leaves the master.key file untouched so existing ciphertexts remain
+     * decryptable if needed.
+     */
+    clearExtensionFile(): Promise<void>;
+    /**
+     * Return a valid `GoogleOAuthPayload`, refreshing via the extension's
+     * cloud function if the access token is within the expiry buffer.
+     *
+     * Concurrent calls for the same credential share a single refresh.
+     *
+     * @throws CredentialRevokedError if the refresh token is no longer valid
+     */
+    getAccessToken(entry: CredentialRegistryEntry, payload: GoogleOAuthPayload): Promise<GoogleOAuthPayload>;
+    private doRefresh;
+    /**
+     * Decrypt the extension's `{iv_hex}:{authTag_hex}:{ciphertext_hex}`
+     * format (AES-256-GCM).
+     */
+    private decryptExtensionFormat;
+    /**
+     * Fetch the user's email via Google's userinfo endpoint. Best-effort;
+     * returns undefined on failure.
+     */
+    private fetchUserEmail;
+}
+/**
+ * Encrypt a plaintext string with the extension's file format. Used in
+ * tests to generate fake token files.
+ */
+export declare function encryptExtensionFormatForTesting(plaintext: string, key: Buffer): string;
+/**
+ * Derive the extension's encryption key using the real scrypt + salt.
+ * Test-only export.
+ */
+export declare function deriveExtensionKeyForTesting(masterKey: Buffer): Buffer;
+//# sourceMappingURL=gemini-cli-workspace.helper.d.ts.map

package/dist/backend/backend/src/services/credential/helpers/gemini-cli-workspace.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-cli-workspace.helper.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/credential/helpers/gemini-cli-workspace.helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAEnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAmDxE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KACxE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAMD;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;IAC/D,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAA0B;IAE7D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAE/C,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG5B;IACJ,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;gBAG9D,KAAK,EAAE,sBAAsB,EAC7B,MAAM,CAAC,EAAE,qBAAqB;IAkBhC;;;;;;OAMG;IACG,eAAe,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAoEpD;;;;;;OAMG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAczC;;;;;;;OAOG;IACG,cAAc,CAClB,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,kBAAkB,CAAC;YA4BhB,SAAS;IAuEvB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAoB9B;;;OAGG;YACW,cAAc;CAe7B;AAMD;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,MAAM,CAOR;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGtE"}

package/dist/backend/backend/src/services/credential/helpers/gemini-cli-workspace.helper.js

@@ -0,0 +1,293 @@
+/**
+ * Gemini CLI Workspace Credential Helper
+ *
+ * Piggybacks on the Google Workspace extension for Gemini CLI
+ * (https://github.com/gemini-cli-extensions/workspace) for Google OAuth
+ * credential acquisition and refresh.
+ *
+ * **Capture** reads the extension's file-storage token file (written when
+ * the user runs the extension with `GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true`)
+ * and imports the tokens into Crewly's own encrypted store.
+ *
+ * **Refresh** POSTs the stored `refresh_token` to the extension's Cloud
+ * Function `/refreshToken` endpoint — no client_secret needed on our side.
+ *
+ * After capture, Crewly owns the tokens; the extension's own state is not
+ * depended on for day-to-day operation.
+ *
+ * @module services/credential/helpers/gemini-cli-workspace.helper
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { CredentialRevokedError, } from '../../../types/credential.types.js';
+// ============================================================================
+// Constants — extracted from the extension source
+// (github.com/gemini-cli-extensions/workspace)
+// ============================================================================
+const DEFAULT_EXTENSION_PATH = path.join(os.homedir(), '.gemini', 'extensions', 'google-workspace');
+const TOKEN_FILENAME = 'gemini-cli-workspace-token.json';
+const MASTER_KEY_FILENAME = '.gemini-cli-workspace-master-key';
+const MAIN_ACCOUNT_KEY = 'main-account';
+const SALT_SUFFIX = '-gemini-cli-workspace';
+const DEFAULT_CLOUD_FUNCTION_URL = 'https://google-workspace-extension.geminicli.com';
+const DEFAULT_REFRESH_PATH = '/refreshToken';
+const DEFAULT_CLIENT_ID = '338689075775-o75k922vn5fdl18qergr96rp8g63e4d7.apps.googleusercontent.com';
+/** Refresh if the current access token expires within this window. */
+const DEFAULT_EXPIRY_BUFFER_MS = 60_000;
+/** Minimum gap between refresh attempts for the same credential. */
+const REFRESH_COOLDOWN_MS = 30_000;
+const USERINFO_ENDPOINT = 'https://www.googleapis.com/oauth2/v3/userinfo';
+// ============================================================================
+// Helper
+// ============================================================================
+/**
+ * Credential helper that reads tokens from the gemini-cli-workspace extension
+ * and refreshes them via the extension's Cloud Function.
+ */
+export class GeminiCliWorkspaceHelper {
+    name = 'gemini-cli-workspace';
+    extensionPath;
+    cloudFunctionUrl;
+    refreshPath;
+    clientId;
+    expiryBufferMs;
+    fetchFn;
+    store;
+    /** Per-credential refresh in-flight promises (serializes concurrent refreshes). */
+    refreshInFlight = new Map();
+    /** Per-credential last refresh attempt timestamp (for cooldown). */
+    lastRefreshAttempt = new Map();
+    constructor(store, config) {
+        this.store = store;
+        this.extensionPath = config?.extensionPath ?? DEFAULT_EXTENSION_PATH;
+        this.cloudFunctionUrl =
+            config?.cloudFunctionUrl ?? DEFAULT_CLOUD_FUNCTION_URL;
+        this.refreshPath = config?.refreshPath ?? DEFAULT_REFRESH_PATH;
+        this.clientId = config?.clientId ?? DEFAULT_CLIENT_ID;
+        this.expiryBufferMs = config?.expiryBufferMs ?? DEFAULT_EXPIRY_BUFFER_MS;
+        this.fetchFn =
+            config?.fetch ??
+                ((url, init) => fetch(url, init));
+    }
+    // ------------------------------------------------------------------
+    //  Capture
+    // ------------------------------------------------------------------
+    /**
+     * Read the extension's current token file and return its contents as a
+     * `GoogleOAuthPayload` ready to persist in Crewly's store.
+     *
+     * The user must have completed extension login with
+     * `GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true` before calling this.
+     */
+    async captureFromFile() {
+        const tokenPath = path.join(this.extensionPath, TOKEN_FILENAME);
+        const masterKeyPath = path.join(this.extensionPath, MASTER_KEY_FILENAME);
+        // Surface a user-friendly error if login hasn't happened yet
+        try {
+            await fs.access(tokenPath);
+        }
+        catch {
+            throw new Error(`Gemini CLI Workspace token file not found at ${tokenPath}. ` +
+                `Please run 'GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true gemini' ` +
+                `and complete Google sign-in first, then retry.`);
+        }
+        try {
+            await fs.access(masterKeyPath);
+        }
+        catch {
+            throw new Error(`Gemini CLI Workspace master key file not found at ${masterKeyPath}. ` +
+                `The extension should create this on first login.`);
+        }
+        const encryptedText = await fs.readFile(tokenPath, 'utf8');
+        const masterKey = await fs.readFile(masterKeyPath);
+        // Derive the extension's encryption key (scrypt with hostname-username salt).
+        // Must match `file-token-storage.ts` exactly.
+        const salt = `${os.hostname()}-${os.userInfo().username}${SALT_SUFFIX}`;
+        const encryptionKey = crypto.scryptSync(masterKey, salt, 32);
+        const decrypted = this.decryptExtensionFormat(encryptedText, encryptionKey);
+        const parsed = JSON.parse(decrypted);
+        const entry = parsed[MAIN_ACCOUNT_KEY];
+        if (!entry) {
+            throw new Error(`Extension token file does not contain a '${MAIN_ACCOUNT_KEY}' entry. ` +
+                `Did login complete successfully?`);
+        }
+        const { accessToken, refreshToken, tokenType, scope, expiresAt } = entry.token;
+        if (!accessToken || !refreshToken) {
+            throw new Error(`Extension token is missing accessToken or refreshToken — login may be incomplete.`);
+        }
+        const scopes = typeof scope === 'string' ? scope.split(' ').filter(Boolean) : [];
+        const accountEmail = await this.fetchUserEmail(accessToken);
+        return {
+            type: 'google-oauth',
+            accessToken,
+            refreshToken,
+            tokenType: tokenType ?? 'Bearer',
+            expiresAt: expiresAt ?? Date.now() + 3600_000,
+            scopes,
+            accountEmail,
+            clientId: this.clientId,
+        };
+    }
+    /**
+     * Remove the extension's token file. Call after `captureFromFile()` to
+     * prepare for the next account's login (the extension otherwise returns
+     * cached credentials if scopes match, skipping the login prompt).
+     * Leaves the master.key file untouched so existing ciphertexts remain
+     * decryptable if needed.
+     */
+    async clearExtensionFile() {
+        const tokenPath = path.join(this.extensionPath, TOKEN_FILENAME);
+        try {
+            await fs.unlink(tokenPath);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return;
+            throw err;
+        }
+    }
+    // ------------------------------------------------------------------
+    //  Refresh / getAccessToken
+    // ------------------------------------------------------------------
+    /**
+     * Return a valid `GoogleOAuthPayload`, refreshing via the extension's
+     * cloud function if the access token is within the expiry buffer.
+     *
+     * Concurrent calls for the same credential share a single refresh.
+     *
+     * @throws CredentialRevokedError if the refresh token is no longer valid
+     */
+    async getAccessToken(entry, payload) {
+        // Fast path: still valid
+        if (payload.expiresAt - Date.now() > this.expiryBufferMs) {
+            return payload;
+        }
+        // Coalesce concurrent refreshes for the same credential
+        const existing = this.refreshInFlight.get(entry.id);
+        if (existing)
+            return existing;
+        // Cooldown — avoid hammering the refresh endpoint
+        const last = this.lastRefreshAttempt.get(entry.id) ?? 0;
+        if (Date.now() - last < REFRESH_COOLDOWN_MS) {
+            // Within cooldown — return the (possibly expired) payload; caller will
+            // get a fresh attempt after the cooldown window.
+            return payload;
+        }
+        const promise = this.doRefresh(entry, payload);
+        this.refreshInFlight.set(entry.id, promise);
+        this.lastRefreshAttempt.set(entry.id, Date.now());
+        try {
+            return await promise;
+        }
+        finally {
+            this.refreshInFlight.delete(entry.id);
+        }
+    }
+    async doRefresh(entry, payload) {
+        const url = this.cloudFunctionUrl.replace(/\/$/, '') + this.refreshPath;
+        const response = await this.fetchFn(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refresh_token: payload.refreshToken }),
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            // Google responds 400 with body containing "invalid_grant" when the
+            // refresh token is revoked/expired beyond recovery.
+            if (response.status === 400 &&
+                /invalid_grant/i.test(body)) {
+                await this.store.updateCredential(entry.id, { status: 'revoked' });
+                throw new CredentialRevokedError(entry.id, entry.name, `Log in to the Gemini CLI Workspace extension again and re-import this credential in Crewly.`);
+            }
+            throw new Error(`Token refresh failed (${response.status}): ${body.slice(0, 500)}`);
+        }
+        const data = (await response.json());
+        if (!data.access_token) {
+            throw new Error('Token refresh response missing access_token');
+        }
+        const expiresAt = Date.now() + (data.expires_in ?? 3600) * 1000;
+        const updated = {
+            ...payload,
+            accessToken: data.access_token,
+            expiresAt,
+            // Google typically does NOT issue a new refresh_token on refresh,
+            // but honor it if present
+            refreshToken: data.refresh_token ?? payload.refreshToken,
+            scopes: typeof data.scope === 'string'
+                ? data.scope.split(' ').filter(Boolean)
+                : payload.scopes,
+        };
+        await this.store.setPayload(entry.id, updated);
+        await this.store.updateCredential(entry.id, {
+            expiresAt,
+            lastUsedAt: new Date().toISOString(),
+        });
+        return updated;
+    }
+    // ------------------------------------------------------------------
+    //  Internals
+    // ------------------------------------------------------------------
+    /**
+     * Decrypt the extension's `{iv_hex}:{authTag_hex}:{ciphertext_hex}`
+     * format (AES-256-GCM).
+     */
+    decryptExtensionFormat(encryptedText, key) {
+        const parts = encryptedText.split(':');
+        if (parts.length !== 3) {
+            throw new Error('Invalid extension token format (expected iv:tag:ciphertext)');
+        }
+        const iv = Buffer.from(parts[0], 'hex');
+        const authTag = Buffer.from(parts[1], 'hex');
+        const ciphertextHex = parts[2];
+        const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(authTag);
+        let decrypted = decipher.update(ciphertextHex, 'hex', 'utf8');
+        decrypted += decipher.final('utf8');
+        return decrypted;
+    }
+    /**
+     * Fetch the user's email via Google's userinfo endpoint. Best-effort;
+     * returns undefined on failure.
+     */
+    async fetchUserEmail(accessToken) {
+        try {
+            const response = await this.fetchFn(USERINFO_ENDPOINT, {
+                method: 'GET',
+                headers: { Authorization: `Bearer ${accessToken}` },
+            });
+            if (!response.ok)
+                return undefined;
+            const data = (await response.json());
+            return data.email;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+// ============================================================================
+// Test helpers (not exported from public barrel — intended for tests only)
+// ============================================================================
+/**
+ * Encrypt a plaintext string with the extension's file format. Used in
+ * tests to generate fake token files.
+ */
+export function encryptExtensionFormatForTesting(plaintext, key) {
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    let encrypted = cipher.update(plaintext, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    const authTag = cipher.getAuthTag();
+    return iv.toString('hex') + ':' + authTag.toString('hex') + ':' + encrypted;
+}
+/**
+ * Derive the extension's encryption key using the real scrypt + salt.
+ * Test-only export.
+ */
+export function deriveExtensionKeyForTesting(masterKey) {
+    const salt = `${os.hostname()}-${os.userInfo().username}${SALT_SUFFIX}`;
+    return crypto.scryptSync(masterKey, salt, 32);
+}
+//# sourceMappingURL=gemini-cli-workspace.helper.js.map

package/dist/backend/backend/src/services/credential/helpers/gemini-cli-workspace.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-cli-workspace.helper.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/credential/helpers/gemini-cli-workspace.helper.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/project/task.service.d.ts

@@ -1,9 +1,15 @@
+export declare const TASK_STATUSES: readonly ["open", "in_progress", "review", "done", "blocked"];
+export type TaskStatus = typeof TASK_STATUSES[number];
+export declare const TASK_PRIORITIES: readonly ["low", "medium", "high", "critical"];
+export type TaskPriority = typeof TASK_PRIORITIES[number];
+export declare function isValidTaskStatus(value: string): value is TaskStatus;
+export declare function isValidTaskPriority(value: string): value is TaskPriority;
 export interface Task {
     id: string;
     title: string;
     description: string;
-    status: 'open' | 'in_progress' | 'review' | 'done' | 'blocked';
-    priority: 'low' | 'medium' | 'high' | 'critical';
+    status: TaskStatus;
+    priority: TaskPriority;
     assignee?: string;
     milestone: string;
     milestoneId: string;
@@ -23,6 +29,16 @@ export declare class TaskService {
     private tasksDir;
     constructor(projectPath?: string);
     private parseMarkdownContent;
+    /**
+     * Read one task markdown file and build a {@link Task}. Returns `null`
+     * when the file can't be read (corrupt, permission denied, missing).
+     *
+     * Status resolution falls back to `statusOverride` when the file's own
+     * `status:` front-matter is missing or invalid — this lets callers
+     * encode status in the folder layout (`milestone/open/foo.md`) without
+     * losing the type narrowing.
+     */
+    private readTaskFile;
     getAllTasks(): Promise<Task[]>;
     getMilestones(): Promise<Milestone[]>;
     getTasksByStatus(status: string): Promise<Task[]>;

package/dist/backend/backend/src/services/project/task.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/project/task.service.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAC/D,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAS;gBAEb,WAAW,CAAC,EAAE,MAAM;IAMhC,OAAO,CAAC,oBAAoB;IA2FtB,WAAW,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IA6H9B,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBrC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAKjD,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;CAIhE"}
+{"version":3,"file":"task.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/project/task.service.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,aAAa,+DAAgE,CAAC;AAC3F,MAAM,MAAM,UAAU,GAAG,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;AAEtD,eAAO,MAAM,eAAe,gDAAiD,CAAC;AAC9E,MAAM,MAAM,YAAY,GAAG,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;AAK1D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAEpE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAExE;AAED,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAS;gBAEb,WAAW,CAAC,EAAE,MAAM;IAMhC,OAAO,CAAC,oBAAoB;IA+F5B;;;;;;;;OAQG;YACW,YAAY;IA6CpB,WAAW,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IA4E9B,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBrC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAKjD,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;CAIhE"}

package/dist/backend/backend/src/services/project/task.service.js

@@ -1,6 +1,16 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { existsSync } from 'fs';
+export const TASK_STATUSES = ['open', 'in_progress', 'review', 'done', 'blocked'];
+export const TASK_PRIORITIES = ['low', 'medium', 'high', 'critical'];
+/** Folder names that indicate a status-partitioned milestone directory. */
+const STATUS_FOLDERS = ['open', 'in_progress', 'done', 'blocked'];
+export function isValidTaskStatus(value) {
+    return TASK_STATUSES.includes(value);
+}
+export function isValidTaskPriority(value) {
+    return TASK_PRIORITIES.includes(value);
+}
 export class TaskService {
     tasksDir;
     constructor(projectPath) {
@@ -11,8 +21,12 @@ export class TaskService {
     parseMarkdownContent(content) {
         const lines = content.split('\n');
         let title = '';
-        let status = 'pending';
-        let priority = 'medium';
+        // Use empty string as the "unset" sentinel — readTaskFile narrows this
+        // through `isValidTaskStatus`/`isValidTaskPriority` and applies the real
+        // defaults. A non-empty sentinel like 'pending' here would be misleading
+        // because 'pending' is not a valid TaskStatus.
+        let status = '';
+        let priority = '';
         let assignee = '';
         let milestone = '';
         let description = '';
@@ -82,6 +96,53 @@ export class TaskService {
             acceptanceCriteria
         };
     }
+    /**
+     * Read one task markdown file and build a {@link Task}. Returns `null`
+     * when the file can't be read (corrupt, permission denied, missing).
+     *
+     * Status resolution falls back to `statusOverride` when the file's own
+     * `status:` front-matter is missing or invalid — this lets callers
+     * encode status in the folder layout (`milestone/open/foo.md`) without
+     * losing the type narrowing.
+     */
+    async readTaskFile(filePath, milestoneId, statusOverride) {
+        try {
+            const [content, stats] = await Promise.all([
+                fs.readFile(filePath, 'utf-8'),
+                fs.stat(filePath),
+            ]);
+            const parsed = this.parseMarkdownContent(content);
+            const fileBase = path.basename(filePath, '.md');
+            const resolvedStatus = statusOverride
+                ?? (isValidTaskStatus(parsed.status) ? parsed.status : 'open');
+            const resolvedPriority = isValidTaskPriority(parsed.priority)
+                ? parsed.priority
+                : 'medium';
+            // Real filesystem timestamps so consumers that sort/cache by
+            // createdAt/updatedAt get stable values across reads. birthtimeMs
+            // falls back to mtime on filesystems that don't track creation time.
+            const createdAt = new Date(stats.birthtimeMs || stats.mtimeMs).toISOString();
+            const updatedAt = new Date(stats.mtimeMs).toISOString();
+            return {
+                id: fileBase,
+                title: parsed.title || fileBase.replace(/_/g, ' '),
+                description: parsed.description,
+                status: resolvedStatus,
+                priority: resolvedPriority,
+                assignee: parsed.assignee,
+                milestone: parsed.milestone || milestoneId,
+                milestoneId,
+                tasks: parsed.tasks,
+                acceptanceCriteria: parsed.acceptanceCriteria,
+                filePath,
+                createdAt,
+                updatedAt,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
     async getAllTasks() {
         if (!existsSync(this.tasksDir)) {
             return [];
@@ -112,11 +173,10 @@ export class TaskService {
             catch {
                 continue;
             }
-            const statusFolders = ['open', 'in_progress', 'done', 'blocked'];
-            const hasStatusFolders = items.some(item => statusFolders.includes(item));
+            const hasStatusFolders = items.some(item => STATUS_FOLDERS.includes(item));
             if (hasStatusFolders) {
                 // Status-based structure: milestone/status/task.md
-                for (const statusFolder of statusFolders) {
+                for (const statusFolder of STATUS_FOLDERS) {
                     const statusPath = path.join(milestonePath, statusFolder);
                     if (!existsSync(statusPath))
                         continue;
@@ -137,31 +197,9 @@ export class TaskService {
                     }
                     const markdownFiles = statusFiles.filter(file => file.endsWith('.md'));
                     for (const file of markdownFiles) {
-                        const filePath = path.join(statusPath, file);
-                        try {
-                            const content = await fs.readFile(filePath, 'utf-8');
-                            const parsed = this.parseMarkdownContent(content);
-                            const task = {
-                                id: path.basename(file, '.md'),
-                                title: parsed.title || path.basename(file, '.md').replace(/_/g, ' '),
-                                description: parsed.description,
-                                status: statusFolder, // Use folder name as status
-                                priority: parsed.priority,
-                                assignee: parsed.assignee,
-                                milestone: parsed.milestone || milestone,
-                                milestoneId: milestone,
-                                tasks: parsed.tasks,
-                                acceptanceCriteria: parsed.acceptanceCriteria,
-                                filePath,
-                                createdAt: new Date().toISOString(),
-                                updatedAt: new Date().toISOString()
-                            };
+                        const task = await this.readTaskFile(path.join(statusPath, file), milestone, statusFolder);
+                        if (task)
                             tasks.push(task);
-                        }
-                        catch {
-                            // Skip files that cannot be read (corrupt, permission denied, etc.)
-                            continue;
-                        }
                     }
                 }
             }
@@ -169,31 +207,9 @@ export class TaskService {
                 // Direct structure: milestone/task.md
                 const markdownFiles = items.filter(file => file.endsWith('.md'));
                 for (const file of markdownFiles) {
-                    const filePath = path.join(milestonePath, file);
-                    try {
-                        const content = await fs.readFile(filePath, 'utf-8');
-                        const parsed = this.parseMarkdownContent(content);
-                        const task = {
-                            id: path.basename(file, '.md'),
-                            title: parsed.title,
-                            description: parsed.description,
-                            status: parsed.status,
-                            priority: parsed.priority,
-                            assignee: parsed.assignee,
-                            milestone: parsed.milestone,
-                            milestoneId: milestone,
-                            tasks: parsed.tasks,
-                            acceptanceCriteria: parsed.acceptanceCriteria,
-                            filePath,
-                            createdAt: new Date().toISOString(),
-                            updatedAt: new Date().toISOString()
-                        };
+                    const task = await this.readTaskFile(path.join(milestonePath, file), milestone);
+                    if (task)
                         tasks.push(task);
-                    }
-                    catch {
-                        // Skip files that cannot be read
-                        continue;
-                    }
                 }
             }
         }