Skip to content

An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.

feat: enable direct context selection and improve session reliability (#1402)

Ralph Khreish6b44a96d9f92
diff --git a/apps/cli/src/commands/context.command.ts b/apps/cli/src/commands/context.command.ts
index 316b0a8e..4ecc0c12 100644
--- a/apps/cli/src/commands/context.command.ts
+++ b/apps/cli/src/commands/context.command.ts
@@ -76,8 +76,9 @@ export class ContextCommand extends Command {
private addOrgCommand(): void {
this.command('org')
.description('Select an organization')
- .action(async () => {
- await this.executeSelectOrg();
+ .argument('[orgId]', 'Organization ID or slug to select directly')
+ .action(async (orgId?: string) => {
+ await this.executeSelectOrg(orgId);
});
}
@@ -87,8 +88,9 @@ export class ContextCommand extends Command {
private addBriefCommand(): void {
this.command('brief')
.description('Select a brief within the current organization')
- .action(async () => {
- await this.executeSelectBrief();
+ .argument('[briefIdOrUrl]', 'Brief ID or Hamster URL to select directly')
+ .action(async (briefIdOrUrl?: string) => {
+ await this.executeSelectBrief(briefIdOrUrl);
});
}
@@ -230,14 +232,14 @@ export class ContextCommand extends Command {
/**
* Execute org selection
*/
- private async executeSelectOrg(): Promise<void> {
+ private async executeSelectOrg(orgId?: string): Promise<void> {
try {
// Check authentication
if (!(await checkAuthentication(this.authManager))) {
process.exit(1);
}
- const result = await this.selectOrganization();
+ const result = await this.selectOrganization(orgId);
this.setLastResult(result);
if (!result.success) {
@@ -252,9 +254,9 @@ export class ContextCommand extends Command {
}
/**
- * Select an organization interactively
+ * Select an organization interactively or by ID/slug/name
*/
- private async selectOrganization(): Promise<ContextResult> {
+ private async selectOrganization(orgId?: string): Promise<ContextResult> {
const spinner = ora('Fetching organizations...').start();
try {
@@ -271,18 +273,57 @@ export class ContextCommand extends Command {
};
}
- // Prompt for selection
- const { selectedOrg } = await inquirer.prompt([
- {
- type: 'list',
- name: 'selectedOrg',
- message: 'Select an organization:',
- choices: organizations.map((org) => ({
- name: org.name,
- value: org
- }))
+ let selectedOrg;
+
+ // If orgId provided, find matching org by ID, slug or name
+ const trimmedOrgId = orgId?.trim();
+ if (trimmedOrgId) {
+ const normalizedInput = trimmedOrgId.toLowerCase();
+ selectedOrg = organizations.find(
+ (org) =>
+ org.id === trimmedOrgId ||
+ org.slug?.toLowerCase() === normalizedInput ||
+ org.name.toLowerCase() === normalizedInput
+ );
+
+ if (!selectedOrg) {
+ const totalCount = organizations.length;
+ const displayLimit = 5;
+ const orgList = organizations
+ .slice(0, displayLimit)
+ .map((o) => o.name)
+ .join(', ');
+
+ let errorMessage = `Organization not found: ${trimmedOrgId}\n`;
+ if (totalCount <= displayLimit) {
+ errorMessage += `Available organizations: ${orgList}`;
+ } else {
+ errorMessage += `Available organizations (showing ${displayLimit} of ${totalCount}): ${orgList}`;
+ errorMessage += `\nRun "tm context org" to see all organizations and select interactively`;
+ }
+
+ ui.displayError(errorMessage);
+ return {
+ success: false,
+ action: 'select-org',
+ message: `Organization not found: ${trimmedOrgId}`
+ };
}
- ]);
+ } else {
+ // Interactive selection
+ const response = await inquirer.prompt([
+ {
+ type: 'list',
+ name: 'selectedOrg',
+ message: 'Select an organization:',
+ choices: organizations.map((org) => ({
+ name: org.name,
+ value: org
+ }))
+ }
+ ]);
+ selectedOrg = response.selectedOrg;
+ }
// Update context
await this.authManager.updateContext({
@@ -311,14 +352,20 @@ export class ContextCommand extends Command {
/**
* Execute brief selection
*/
- private async executeSelectBrief(): Promise<void> {
+ private async executeSelectBrief(briefIdOrUrl?: string): Promise<void> {
try {
// Check authentication
if (!(await checkAuthentication(this.authManager))) {
process.exit(1);
}
- // Check if org is selected
+ // If briefIdOrUrl provided, use direct selection
+ if (briefIdOrUrl && briefIdOrUrl.trim().length > 0) {
+ await this.selectBriefDirectly(briefIdOrUrl.trim(), 'select-brief');
+ return;
+ }
+
+ // Interactive selection
const context = this.authManager.getContext();
if (!context?.orgId) {
ui.displayError(
@@ -428,6 +475,34 @@ export class ContextCommand extends Command {
}
}
+ /**
+ * Helper method to select brief directly from input (URL or ID)
+ * Used by both executeSelectBrief and executeSetFromBriefInput
+ */
+ private async selectBriefDirectly(
+ input: string,
+ action: 'select-brief' | 'set'
+ ): Promise<void> {
+ await this.initTmCore();
+
+ const result = await selectBriefFromInput(
+ this.authManager,
+ input,
+ this.tmCore
+ );
+
+ this.setLastResult({
+ success: result.success,
+ action,
+ context: this.authManager.getContext() || undefined,
+ message: result.message
+ });
+
+ if (!result.success) {
+ process.exit(1);
+ }
+ }
+
/**
* Execute setting context from a brief ID or Hamster URL
* All parsing logic is in tm-core
@@ -439,26 +514,7 @@ export class ContextCommand extends Command {
process.exit(1);
}
- // Initialize tmCore to access business logic
- await this.initTmCore();
-
- // Use shared utility - tm-core handles ALL parsing
- const result = await selectBriefFromInput(
- this.authManager,
- input,
- this.tmCore
- );
-
- this.setLastResult({
- success: result.success,
- action: 'set',
- context: this.authManager.getContext() || undefined,
- message: result.message
- });
-
- if (!result.success) {
- process.exit(1);
- }
+ await this.selectBriefDirectly(input, 'set');
} catch (error: any) {
ui.displayError(
`Failed to set context from brief: ${(error as Error).message}`
diff --git a/packages/tm-core/src/modules/auth/services/supabase-session-storage.spec.ts b/packages/tm-core/src/modules/auth/services/supabase-session-storage.spec.ts
new file mode 100644
index 00000000..9719a837
--- /dev/null
+++ b/packages/tm-core/src/modules/auth/services/supabase-session-storage.spec.ts
@@ -0,0 +1,214 @@
+/**
+ * Tests for SupabaseSessionStorage
+ * Verifies session persistence with steno atomic writes
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import os from 'os';
+import path from 'path';
+import { SupabaseSessionStorage } from './supabase-session-storage.js';
+
+describe('SupabaseSessionStorage', () => {
+ let tempDir: string;
+ let sessionPath: string;
+
+ beforeEach(() => {
+ // Create unique temp directory for each test
+ tempDir = fsSync.mkdtempSync(path.join(os.tmpdir(), 'tm-session-test-'));
+ sessionPath = path.join(tempDir, 'session.json');
+ });
+
+ afterEach(() => {
+ // Clean up temp directory
+ if (fsSync.existsSync(tempDir)) {
+ fsSync.rmSync(tempDir, { recursive: true, force: true });
+ }
+ });
+
+ describe('persistence with steno', () => {
+ it('should immediately persist data to disk with setItem', async () => {
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ // Set a session token
+ const testSession = JSON.stringify({
+ access_token: 'test-token',
+ refresh_token: 'test-refresh'
+ });
+ await storage.setItem('sb-localhost-auth-token', testSession);
+
+ // Immediately verify file exists and is readable (without any delay)
+ expect(fsSync.existsSync(sessionPath)).toBe(true);
+
+ // Read directly from disk (simulating a new process)
+ const diskData = JSON.parse(fsSync.readFileSync(sessionPath, 'utf8'));
+ expect(diskData['sb-localhost-auth-token']).toBe(testSession);
+ });
+
+ it('should guarantee data is on disk before returning', async () => {
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ // Write large session data
+ const largeSession = JSON.stringify({
+ access_token: 'x'.repeat(10000),
+ refresh_token: 'y'.repeat(10000),
+ user: { id: 'test', email: '[email protected]' }
+ });
+
+ await storage.setItem('sb-localhost-auth-token', largeSession);
+
+ // Create a NEW storage instance (simulates separate CLI command)
+ const newStorage = new SupabaseSessionStorage(sessionPath);
+
+ // Should immediately read the persisted data
+ const retrieved = await newStorage.getItem('sb-localhost-auth-token');
+ expect(retrieved).toBe(largeSession);
+ });
+
+ it('should handle rapid sequential writes without data loss', async () => {
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ // Simulate rapid token updates (like during refresh)
+ for (let i = 0; i < 5; i++) {
+ const session = JSON.stringify({
+ access_token: `token-${i}`,
+ expires_at: Date.now() + i * 1000
+ });
+ await storage.setItem('sb-localhost-auth-token', session);
+
+ // Each write should be immediately readable
+ const newStorage = new SupabaseSessionStorage(sessionPath);
+ const retrieved = await newStorage.getItem('sb-localhost-auth-token');
+ expect(JSON.parse(retrieved!).access_token).toBe(`token-${i}`);
+ }
+ });
+ });
+
+ describe('atomic writes', () => {
+ it('should complete writes atomically without leaving temp files', async () => {
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ await storage.setItem('test-key', 'test-value');
+
+ // Final file should exist with correct content
+ expect(fsSync.existsSync(sessionPath)).toBe(true);
+ const diskData = JSON.parse(fsSync.readFileSync(sessionPath, 'utf8'));
+ expect(diskData['test-key']).toBe('test-value');
+
+ // No unexpected extra files should remain in directory
+ const files = fsSync.readdirSync(path.dirname(sessionPath));
+ expect(files).toEqual([path.basename(sessionPath)]);
+ });
+
+ it('should maintain correct file permissions (0700 for directory)', async () => {
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ await storage.setItem('test-key', 'test-value');
+
+ // Check that file exists
+ expect(fsSync.existsSync(sessionPath)).toBe(true);
+
+ // Check directory has correct permissions
+ const dir = path.dirname(sessionPath);
+ const stats = fsSync.statSync(dir);
+ const mode = stats.mode & 0o777;
+
+ // Directory should be readable/writable/executable by owner only (0700)
+ expect(mode).toBe(0o700);
+ });
+ });
+
+ describe('basic operations', () => {
+ it('should get and set items', async () => {
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ await storage.setItem('key1', 'value1');
+ expect(await storage.getItem('key1')).toBe('value1');
+ });
+
+ it('should return null for non-existent items', async () => {
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ expect(await storage.getItem('non-existent')).toBe(null);
+ });
+
+ it('should remove items', async () => {
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ await storage.setItem('key1', 'value1');
+ expect(await storage.getItem('key1')).toBe('value1');
+
+ await storage.removeItem('key1');
+ expect(await storage.getItem('key1')).toBe(null);
+
+ // Verify removed from disk
+ const newStorage = new SupabaseSessionStorage(sessionPath);
+ expect(await newStorage.getItem('key1')).toBe(null);
+ });
+ });
+
+ describe('initialization', () => {
+ it('should load existing session on initialization', async () => {
+ // Create initial storage and save data
+ const storage1 = new SupabaseSessionStorage(sessionPath);
+ await storage1.setItem('key1', 'value1');
+
+ // Create new instance (simulates new process)
+ const storage2 = new SupabaseSessionStorage(sessionPath);
+ expect(await storage2.getItem('key1')).toBe('value1');
+ });
+
+ it('should handle non-existent session file gracefully', async () => {
+ // Don't create any file, just initialize
+ const storage = new SupabaseSessionStorage(sessionPath);
+
+ // Should not throw and should work normally
+ expect(await storage.getItem('any-key')).toBe(null);
+ await storage.setItem('key1', 'value1');
+ expect(await storage.getItem('key1')).toBe('value1');
+ });
+
+ it('should create directory if it does not exist', async () => {
+ const deepPath = path.join(
+ tempDir,
+ 'deep',
+ 'nested',
+ 'path',
+ 'session.json'
+ );
+ const storage = new SupabaseSessionStorage(deepPath);
+
+ await storage.setItem('key1', 'value1');
+
+ expect(fsSync.existsSync(deepPath)).toBe(true);
+ expect(fsSync.existsSync(path.dirname(deepPath))).toBe(true);
+ });
+ });
+
+ describe('error handling', () => {
+ it('should not throw on persist errors', async () => {
+ const invalidPath = '/invalid/path/that/cannot/be/written/session.json';
+ const storage = new SupabaseSessionStorage(invalidPath);
+
+ // Should not throw, session should remain in memory
+ await storage.setItem('key1', 'value1');
+
+ // Should still work in memory
+ expect(await storage.getItem('key1')).toBe('value1');
+ });
+
+ it('should handle corrupted session file gracefully', async () => {
+ // Write corrupted JSON
+ fsSync.writeFileSync(sessionPath, 'invalid json {{{');
+
+ // Should not throw on initialization
+ expect(() => new SupabaseSessionStorage(sessionPath)).not.toThrow();
+
+ // Should work normally after initialization
+ const storage = new SupabaseSessionStorage(sessionPath);
+ await storage.setItem('key1', 'value1');
+ expect(await storage.getItem('key1')).toBe('value1');
+ });
+ });
+});
diff --git a/packages/tm-core/src/modules/auth/services/supabase-session-storage.ts b/packages/tm-core/src/modules/auth/services/supabase-session-storage.ts
index 63b5a8a7..117b818d 100644
--- a/packages/tm-core/src/modules/auth/services/supabase-session-storage.ts
+++ b/packages/tm-core/src/modules/auth/services/supabase-session-storage.ts
@@ -11,11 +11,13 @@
*
* We handle:
* - Simple get/set/remove/clear operations
- * - Persistence to ~/.taskmaster/session.json
+ * - Persistence to ~/.taskmaster/session.json with atomic writes via steno
*/
-import fs from 'fs';
+import fs from 'fs/promises';
+import fsSync from 'fs';
import path from 'path';
+import { Writer } from 'steno';
import type { SupportedStorage } from '@supabase/supabase-js';
import { getLogger } from '../../../common/logger/index.js';
@@ -29,19 +31,27 @@ export class SupabaseSessionStorage implements SupportedStorage {
private storage: Map<string, string> = new Map();
private persistPath: string;
private logger = getLogger('SupabaseSessionStorage');
+ private writer: Writer;
+ private initPromise: Promise<void>;
constructor(persistPath: string = DEFAULT_SESSION_FILE) {
this.persistPath = persistPath;
- this.load();
+ this.writer = new Writer(persistPath);
+ this.initPromise = this.load();
}
/**
* Load session data from disk on initialization
*/
- private load(): void {
+ private async load(): Promise<void> {
try {
- if (fs.existsSync(this.persistPath)) {
- const data = JSON.parse(fs.readFileSync(this.persistPath, 'utf8'));
+ // Ensure directory exists
+ const dir = path.dirname(this.persistPath);
+ await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+
+ // Try to read existing session
+ if (fsSync.existsSync(this.persistPath)) {
+ const data = JSON.parse(await fs.readFile(this.persistPath, 'utf8'));
Object.entries(data).forEach(([k, v]) =>
this.storage.set(k, v as string)
);
@@ -57,24 +67,19 @@ export class SupabaseSessionStorage implements SupportedStorage {
/**
* Persist session data to disk immediately
+ * Uses steno for atomic writes with fsync guarantees
+ * This prevents race conditions in rapid CLI command sequences
*/
- private persist(): void {
+ private async persist(): Promise<void> {
try {
- // Ensure directory exists
- const dir = path.dirname(this.persistPath);
- if (!fs.existsSync(dir)) {
- fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
- }
-
- // Write atomically with temp file
const data = Object.fromEntries(this.storage);
- const tempFile = `${this.persistPath}.tmp`;
- fs.writeFileSync(tempFile, JSON.stringify(data, null, 2), {
- mode: 0o600
- });
- fs.renameSync(tempFile, this.persistPath);
+ const jsonContent = JSON.stringify(data, null, 2);
- this.logger.debug('Persisted session to disk');
+ // steno handles atomic writes with temp file + rename
+ // and ensures data is flushed to disk
+ await this.writer.write(jsonContent + '\n');
+
+ this.logger.debug('Persisted session to disk (steno)');
} catch (error) {
this.logger.error('Failed to persist session:', error);
// Don't throw - session is still in memory
@@ -84,8 +89,12 @@ export class SupabaseSessionStorage implements SupportedStorage {
/**
* Get item from storage
* Supabase will call this to retrieve session data
+ * Returns a promise to ensure initialization completes first
*/
- getItem(key: string): string | null {
+ async getItem(key: string): Promise<string | null> {
+ // Wait for initialization to complete
+ await this.initPromise;
+
const value = this.storage.get(key) ?? null;
this.logger.debug('getItem called', { key, hasValue: !!value });
return value;
@@ -96,28 +105,41 @@ export class SupabaseSessionStorage implements SupportedStorage {
* Supabase will call this to store/update session data
* CRITICAL: This is called during token refresh - must persist immediately
*/
- setItem(key: string, value: string): void {
+ async setItem(key: string, value: string): Promise<void> {
+ // Wait for initialization to complete
+ await this.initPromise;
+
this.logger.debug('setItem called', { key });
this.storage.set(key, value);
- this.persist(); // Immediately persist on every write
+
+ // Immediately persist on every write
+ // steno ensures atomic writes with fsync
+ await this.persist();
}
/**
* Remove item from storage
* Supabase will call this during sign out
*/
- removeItem(key: string): void {
+ async removeItem(key: string): Promise<void> {
+ // Wait for initialization to complete
+ await this.initPromise;
+
this.logger.debug('removeItem called', { key });
this.storage.delete(key);
- this.persist();
+ await this.persist();
}
/**
* Clear all session data
+ * Useful for complete logout scenarios
*/
- clear(): void {
+ async clear(): Promise<void> {
+ // Wait for initialization to complete
+ await this.initPromise;
+
this.logger.debug('clear called');
this.storage.clear();
- this.persist();
+ await this.persist();
}
}
diff --git a/packages/tm-core/src/modules/briefs/briefs-domain.ts b/packages/tm-core/src/modules/briefs/briefs-domain.ts
index 68c4158b..a3151eb7 100644
--- a/packages/tm-core/src/modules/briefs/briefs-domain.ts
+++ b/packages/tm-core/src/modules/briefs/briefs-domain.ts
@@ -10,6 +10,7 @@ import {
import { AuthManager } from '../auth/managers/auth-manager.js';
import type { TaskRepository } from '../tasks/repositories/task-repository.interface.js';
import { BriefService, type TagWithStats } from './services/brief-service.js';
+import { BriefUrlParser } from './utils/url-parser.js';
/**
* Briefs Domain - Unified API for brief operations
@@ -35,15 +36,38 @@ export class BriefsDomain {
* - Brief name (exact or partial match)
*
* @param input - Raw input: URL, UUID, last 8 chars, or brief name
- * @param orgId - Optional organization ID. If not provided, uses current context.
+ * @param orgId - Optional organization ID. If not provided, tries to extract from URL or uses current context.
* @returns The resolved brief object
*/
async resolveBrief(input: string, orgId?: string): Promise<any> {
- // Extract brief ID/name from input (could be URL, ID, or name)
- const briefIdOrName = this.extractBriefIdentifier(input);
+ // Parse input using dedicated URL parser
+ const parsed = BriefUrlParser.parse(input);
+ const briefIdOrName = parsed.briefId || input.trim();
- // Get org ID from parameter or context
- const resolvedOrgId = orgId || this.authManager.getContext()?.orgId;
+ // Resolve organization ID (priority: parameter > URL > context)
+ let resolvedOrgId = orgId;
+
+ // Try to extract org slug from URL if not provided
+ if (!resolvedOrgId && parsed.orgSlug) {
+ try {
+ const orgs = await this.authManager.getOrganizations();
+ const matchingOrg = orgs.find(
+ (org) =>
+ org.slug?.toLowerCase() === parsed.orgSlug?.toLowerCase() ||
+ org.name.toLowerCase() === parsed.orgSlug?.toLowerCase()
+ );
+ if (matchingOrg) {
+ resolvedOrgId = matchingOrg.id;
+ }
+ } catch {
+ // If we can't fetch orgs, fall through to context
+ }
+ }
+
+ // Fall back to context if still not resolved
+ if (!resolvedOrgId) {
+ resolvedOrgId = this.authManager.getContext()?.orgId;
+ }
if (!resolvedOrgId) {
throw new TaskMasterError(
@@ -66,64 +90,6 @@ export class BriefsDomain {
return matchingBrief;
}
- /**
- * Extract brief identifier from raw input
- * Handles URLs, paths, and direct IDs
- *
- * @param input - Raw input string
- * @returns Extracted brief identifier
- */
- private extractBriefIdentifier(input: string): string {
- const raw = input?.trim() ?? '';
- if (!raw) {
- throw new TaskMasterError(
- 'Brief identifier cannot be empty',
- ERROR_CODES.VALIDATION_ERROR
- );
- }
-
- const parseUrl = (s: string): URL | null => {
- try {
- return new URL(s);
- } catch {}
- try {
- return new URL(`https://${s}`);
- } catch {}
- return null;
- };
-
- const fromParts = (path: string): string | null => {
- const parts = path.split('/').filter(Boolean);
- const briefsIdx = parts.lastIndexOf('briefs');
- const candidate =
- briefsIdx >= 0 && parts.length > briefsIdx + 1
- ? parts[briefsIdx + 1]
- : parts[parts.length - 1];
- return candidate?.trim() || null;
- };
-
- // 1) URL (absolute or scheme‑less)
- const url = parseUrl(raw);
- if (url) {
- const qId = url.searchParams.get('id') || url.searchParams.get('briefId');
- const candidate = (qId || fromParts(url.pathname)) ?? null;
- if (candidate) {
- return candidate;
- }
- }
-
- // 2) Looks like a path without scheme
- if (raw.includes('/')) {
- const candidate = fromParts(raw);
- if (candidate) {
- return candidate;
- }
- }
-
- // 3) Fallback: raw token (UUID, last 8 chars, or name)
- return raw;
- }
-
/**
* Switch to a different brief by name or ID
* Validates context, finds matching brief, and updates auth context
diff --git a/packages/tm-core/src/modules/briefs/utils/url-parser.ts b/packages/tm-core/src/modules/briefs/utils/url-parser.ts
new file mode 100644
index 00000000..3af15c39
--- /dev/null
+++ b/packages/tm-core/src/modules/briefs/utils/url-parser.ts
@@ -0,0 +1,152 @@
+/**
+ * @fileoverview URL Parser
+ * Utility for parsing URLs to extract organization and brief identifiers
+ */
+
+import {
+ ERROR_CODES,
+ TaskMasterError
+} from '../../../common/errors/task-master-error.js';
+
+export interface ParsedBriefUrl {
+ orgSlug: string | null;
+ briefId: string | null;
+}
+
+/**
+ * Utility class for parsing brief URLs
+ * Handles URL formats like: http://localhost:3000/home/{orgSlug}/briefs/{briefId}
+ */
+export class BriefUrlParser {
+ /**
+ * Parse a URL and extract org slug and brief ID
+ *
+ * @param input - Raw input string (URL, path, or ID)
+ * @returns Parsed components
+ */
+ static parse(input: string): ParsedBriefUrl {
+ const raw = input?.trim() ?? '';
+ if (!raw) {
+ return { orgSlug: null, briefId: null };
+ }
+
+ // Try parsing as URL
+ const url = this.parseAsUrl(raw);
+ const pathToCheck = url ? url.pathname : raw.includes('/') ? raw : null;
+
+ if (!pathToCheck) {
+ // Not a URL/path, treat as direct ID
+ return { orgSlug: null, briefId: raw };
+ }
+
+ // Extract components from path
+ return this.parsePathComponents(pathToCheck, url);
+ }
+
+ /**
+ * Extract organization slug from URL or path
+ *
+ * @param input - Raw input string
+ * @returns Organization slug or null
+ */
+ static extractOrgSlug(input: string): string | null {
+ return this.parse(input).orgSlug;
+ }
+
+ /**
+ * Extract brief identifier from URL or path
+ *
+ * @param input - Raw input string
+ * @returns Brief identifier or null
+ */
+ static extractBriefId(input: string): string | null {
+ const parsed = this.parse(input);
+ return parsed.briefId || input.trim();
+ }
+
+ /**
+ * Try to parse input as URL
+ * Handles both absolute and scheme-less URLs
+ */
+ private static parseAsUrl(input: string): URL | null {
+ try {
+ return new URL(input);
+ } catch {}
+ try {
+ return new URL(`https://${input}`);
+ } catch {}
+ return null;
+ }
+
+ /**
+ * Parse path components to extract org slug and brief ID
+ * Handles patterns like: /home/{orgSlug}/briefs/{briefId}
+ */
+ private static parsePathComponents(
+ path: string,
+ url: URL | null
+ ): ParsedBriefUrl {
+ const parts = path.split('/').filter(Boolean);
+ const briefsIdx = parts.lastIndexOf('briefs');
+
+ let orgSlug: string | null = null;
+ let briefId: string | null = null;
+
+ // Extract org slug (segment before 'briefs')
+ if (briefsIdx > 0) {
+ orgSlug = parts[briefsIdx - 1] || null;
+ }
+
+ // Extract brief ID
+ // Priority: query param > path segment after 'briefs' > last segment (if not 'briefs')
+ if (url) {
+ const qId = url.searchParams.get('id') || url.searchParams.get('briefId');
+ if (qId) {
+ briefId = qId;
+ }
+ }
+
+ if (!briefId && briefsIdx >= 0 && parts.length > briefsIdx + 1) {
+ briefId = parts[briefsIdx + 1];
+ }
+
+ // Only use last segment as fallback if path doesn't end with 'briefs'
+ // This prevents treating '/home/org/briefs' as briefId='briefs'
+ if (
+ !briefId &&
+ parts.length > 0 &&
+ !(briefsIdx >= 0 && briefsIdx === parts.length - 1)
+ ) {
+ briefId = parts[parts.length - 1];
+ }
+
+ return { orgSlug, briefId };
+ }
+
+ /**
+ * Validate that required components are present
+ *
+ * @param parsed - Parsed URL components
+ * @param requireOrg - Whether org slug is required
+ * @param requireBrief - Whether brief ID is required
+ * @throws TaskMasterError if required components are missing
+ */
+ static validate(
+ parsed: ParsedBriefUrl,
+ options: { requireOrg?: boolean; requireBrief?: boolean } = {}
+ ): void {
+ if (options.requireOrg && !parsed.orgSlug) {
+ throw new TaskMasterError(
+ 'Organization slug could not be extracted from input',
+ ERROR_CODES.VALIDATION_ERROR
+ );
+ }
+
+ if (options.requireBrief && !parsed.briefId) {
+ throw new TaskMasterError(
+ 'Brief identifier could not be extracted from input',
+ ERROR_CODES.VALIDATION_ERROR
+ );
+ }
+ }
+}