@taskforcehq/taskforce 0.3.169 → 0.3.300

package/dist/server/routes/resources.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resource and workflow route module.
+ *
+ * Handles filesystem browsing helpers, resource export, workflow template
+ * reads, workflow editor override persistence, and environment discovery.
+ *
+ * Routes registered here:
+ *   GET  /api/taskforce/folders
+ *   POST /api/taskforce/validate-paths
+ *   POST /api/taskforce/export-resources
+ *   GET  /api/taskforce/workflow-templates
+ *   GET  /api/taskforce/workflow-template/:name
+ *   GET  /api/taskforce/workflow-templates/:name
+ *   GET  /api/taskforce/workflow-editor/overrides
+ *   POST /api/taskforce/workflow-editor/save
+ *   POST /api/taskforce/workflow-editor/reset/:name
+ *   GET  /api/taskforce/environments
+ */
+import type { TaskforceCore } from '../../core/Taskforce.js';
+import { type RouteHandler } from '../routes.js';
+export interface ResourceRouteDependencies {
+    addRoute: (method: string, path: string, handler: RouteHandler) => void;
+    core: TaskforceCore;
+}
+export declare function registerResourceRoutes(deps: ResourceRouteDependencies): void;

package/dist/server/routes/resources.js

@@ -0,0 +1,225 @@
+/**
+ * Resource and workflow route module.
+ *
+ * Handles filesystem browsing helpers, resource export, workflow template
+ * reads, workflow editor override persistence, and environment discovery.
+ *
+ * Routes registered here:
+ *   GET  /api/taskforce/folders
+ *   POST /api/taskforce/validate-paths
+ *   POST /api/taskforce/export-resources
+ *   GET  /api/taskforce/workflow-templates
+ *   GET  /api/taskforce/workflow-template/:name
+ *   GET  /api/taskforce/workflow-templates/:name
+ *   GET  /api/taskforce/workflow-editor/overrides
+ *   POST /api/taskforce/workflow-editor/save
+ *   POST /api/taskforce/workflow-editor/reset/:name
+ *   GET  /api/taskforce/environments
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { parseJsonBody } from '../routes.js';
+const WORKFLOW_EDITOR_LOCKED_FIELDS = {
+    do: ['aliasesText', 'dispatchDefault', 'criticalToolsText', 'contentDefault'],
+    execute: ['aliasesText', 'dispatchDefault', 'criticalToolsText', 'contentDefault']
+};
+function draftFromTemplate(template) {
+    return {
+        description: String(template?.description || ''),
+        aliasesText: Array.isArray(template?.dispatch?.aliases) ? template.dispatch.aliases.join(', ') : '',
+        dispatchDefault: String(template?.dispatch?.default || ''),
+        criticalToolsText: Array.isArray(template?.compat?.requiredToolsCritical) ? template.compat.requiredToolsCritical.join('\n') : '',
+        optionalToolsText: Array.isArray(template?.compat?.requiredToolsOptional) ? template.compat.requiredToolsOptional.join('\n') : '',
+        contentDefault: String(template?.content?.default || '')
+    };
+}
+function sanitizeWorkflowEditorDraft(name, draft, template) {
+    const lockedFields = WORKFLOW_EDITOR_LOCKED_FIELDS[name] || [];
+    if (lockedFields.length === 0)
+        return draft;
+    const baseDraft = draftFromTemplate(template);
+    const next = { ...draft };
+    for (const key of lockedFields) {
+        if (Object.prototype.hasOwnProperty.call(baseDraft, key)) {
+            next[key] = baseDraft[key];
+        }
+    }
+    return next;
+}
+export function registerResourceRoutes(deps) {
+    const { addRoute, core } = deps;
+    addRoute('GET', '/api/taskforce/folders', async (req, res) => {
+        const url = new URL(req.url || '', 'http://localhost');
+        const requestedPath = url.searchParams.get('path') || '';
+        const { projectRoot } = core.getPaths();
+        const fullPath = requestedPath ? path.resolve(projectRoot, requestedPath) : projectRoot;
+        const realPath = fs.existsSync(fullPath) ? fs.realpathSync(fullPath) : fullPath;
+        if (!realPath.startsWith(projectRoot)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Access denied' }));
+            return;
+        }
+        if (!fs.existsSync(realPath) || !fs.statSync(realPath).isDirectory()) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ folders: [], files: [] }));
+            return;
+        }
+        const entries = fs.readdirSync(realPath, { withFileTypes: true });
+        const folders = entries
+            .filter((entry) => {
+            if (entry.name.startsWith('.') && entry.name !== '.agent')
+                return false;
+            if (entry.name === 'node_modules')
+                return false;
+            return entry.isDirectory();
+        })
+            .map((entry) => entry.name)
+            .sort();
+        const files = entries
+            .filter((entry) => !entry.name.startsWith('.') && entry.isFile())
+            .map((entry) => entry.name)
+            .sort();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ folders, files }));
+    });
+    addRoute('POST', '/api/taskforce/validate-paths', async (req, res) => {
+        const body = await parseJsonBody(req);
+        const { paths } = body;
+        const { projectRoot } = core.getPaths();
+        const results = {};
+        if (Array.isArray(paths)) {
+            for (const candidatePath of paths) {
+                const fullPath = path.resolve(projectRoot, candidatePath);
+                if (fs.existsSync(fullPath)) {
+                    const stats = fs.statSync(fullPath);
+                    results[candidatePath] = {
+                        exists: true,
+                        isDirectory: stats.isDirectory(),
+                        isFile: stats.isFile()
+                    };
+                }
+                else {
+                    results[candidatePath] = { exists: false, isDirectory: false, isFile: false };
+                }
+            }
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ results }));
+    });
+    addRoute('POST', '/api/taskforce/export-resources', async (req, res) => {
+        const body = await parseJsonBody(req);
+        const { type, path: destRelativePath, variables, environment, workflowNames } = body;
+        try {
+            let count;
+            if ((type === 'workflows' || type === 'workflow') && workflowNames && Array.isArray(workflowNames)) {
+                count = core.exportWorkflows(environment || 'antigravity', workflowNames, variables);
+            }
+            else {
+                count = core.exportResources(type, destRelativePath, variables, environment);
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, count }));
+        }
+        catch (error) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message }));
+        }
+    });
+    addRoute('GET', '/api/taskforce/workflow-templates', async (_req, res) => {
+        const templates = core.listWorkflowTemplates();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ templates }));
+    });
+    const workflowTemplateHandler = async (_req, res, params) => {
+        const name = (params?.name || '').trim();
+        if (!name) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Template name is required' }));
+            return;
+        }
+        try {
+            const template = core.getWorkflowTemplate(name);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ template }));
+        }
+        catch (error) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: error.message }));
+        }
+    };
+    addRoute('GET', '/api/taskforce/workflow-template/:name', workflowTemplateHandler);
+    addRoute('GET', '/api/taskforce/workflow-templates/:name', workflowTemplateHandler);
+    addRoute('GET', '/api/taskforce/workflow-editor/overrides', async (_req, res) => {
+        const names = core.listWorkflowOverrideNames();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ names }));
+    });
+    addRoute('POST', '/api/taskforce/workflow-editor/save', async (req, res) => {
+        const body = await parseJsonBody(req);
+        const { name, draft } = body || {};
+        if (!name || typeof name !== 'string') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Workflow name is required' }));
+            return;
+        }
+        if (!draft || typeof draft !== 'object') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Draft payload is required' }));
+            return;
+        }
+        const root = core.getPaths().projectRoot;
+        const overridesPath = path.resolve(root, 'src/resources/templates/workflow-sources/workflowEditorOverrides.json');
+        try {
+            const template = core.getWorkflowTemplate(name);
+            const sanitizedDraft = sanitizeWorkflowEditorDraft(name, draft, template);
+            const raw = fs.existsSync(overridesPath) ? fs.readFileSync(overridesPath, 'utf8') : '{}';
+            const parsed = raw.trim() ? JSON.parse(raw) : {};
+            parsed[name] = {
+                ...parsed[name],
+                ...sanitizedDraft,
+                updatedAt: new Date().toISOString()
+            };
+            fs.writeFileSync(overridesPath, JSON.stringify(parsed, null, 2), 'utf8');
+            const generatorPath = path.resolve(root, 'scripts/generate-workflow-templates.mjs');
+            execFileSync('node', [generatorPath], { cwd: root, stdio: 'pipe' });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true }));
+        }
+        catch (error) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/workflow-editor/reset/:name', async (_req, res, params) => {
+        const name = (params?.name || '').trim();
+        if (!name) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Workflow name is required' }));
+            return;
+        }
+        const root = core.getPaths().projectRoot;
+        const overridesPath = path.resolve(root, 'src/resources/templates/workflow-sources/workflowEditorOverrides.json');
+        try {
+            const raw = fs.existsSync(overridesPath) ? fs.readFileSync(overridesPath, 'utf8') : '{}';
+            const parsed = raw.trim() ? JSON.parse(raw) : {};
+            if (Object.prototype.hasOwnProperty.call(parsed, name)) {
+                delete parsed[name];
+                fs.writeFileSync(overridesPath, JSON.stringify(parsed, null, 2), 'utf8');
+            }
+            const generatorPath = path.resolve(root, 'scripts/generate-workflow-templates.mjs');
+            execFileSync('node', [generatorPath], { cwd: root, stdio: 'pipe' });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true }));
+        }
+        catch (error) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message }));
+        }
+    });
+    addRoute('GET', '/api/taskforce/environments', async (_req, res) => {
+        const environments = core.listEnvironments();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ environments }));
+    });
+}

package/dist/server/routes/shared.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared route helpers and middleware factories.
+ *
+ * These utilities are injected into every route module via their
+ * `*RouteDependencies` interface so that no module needs to reach back into
+ * routes.ts at runtime.
+ */
+import { IncomingMessage, ServerResponse } from 'http';
+import { TaskforceCore } from '../../core/Taskforce.js';
+import type { RouteContext } from '../routes.js';
+export declare function resolveErrorStatusCode(error: unknown, fallback?: number): number;
+export declare function requestHeader(req: IncomingMessage, name: string, fallback?: string): string;
+export declare function requestWorkspaceHeader(req: IncomingMessage): string;
+export declare function requestAuthoritativeWorkspaceId(req: IncomingMessage): string;
+export declare function requestRuntimeMode(req: IncomingMessage): 'local' | 'cloud';
+export declare function requestRole(req: IncomingMessage): string;
+export declare function requestSystemRole(req: IncomingMessage): 'system_admin' | 'user';
+export declare function requestUserId(req: IncomingMessage): string;
+export declare function makeRequestWorkspaceId(core: TaskforceCore, context: RouteContext): (req: IncomingMessage) => string;
+export declare function makeResolveAuthenticatedUserId(core: TaskforceCore, context: RouteContext, requestWorkspaceId: (req: IncomingMessage) => string): (req: IncomingMessage) => string;
+export declare function makeResolveAuthenticatedMutationUserId(core: TaskforceCore, context: RouteContext, requestWorkspaceId: (req: IncomingMessage) => string): (req: IncomingMessage) => string;
+export declare function makeEnsureAppAccess(core: TaskforceCore, context: RouteContext): (req: IncomingMessage, res: ServerResponse) => boolean;
+export declare function makeEnsureAdminRole(core: TaskforceCore, context: RouteContext): (req: IncomingMessage) => boolean;
+export declare function makeEnsureAuthenticatedUser(): (req: IncomingMessage) => boolean;
+export declare function ensureOwnerRole(req: IncomingMessage): boolean;
+export declare function ensureWorkspaceAdminRole(req: IncomingMessage): boolean;
+export declare function makeResolveAdminRequestActor(core: TaskforceCore, context: RouteContext): (req: IncomingMessage) => {
+    authenticated: boolean;
+    userId: string;
+    systemRole: "system_admin" | "user";
+};
+export declare function makeAuditAdminAction(core: TaskforceCore, context: RouteContext): (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
+export declare function makeAuditAuthAction(core: TaskforceCore, requestWorkspaceId: (req: IncomingMessage) => string): (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
+export declare function makeRequireCloudRuntime(context: RouteContext): (res: ServerResponse, feature: string) => boolean;
+export declare function makeEnsureCloudPlanData(context: RouteContext): (req: IncomingMessage, res: ServerResponse) => boolean;

package/dist/server/routes/shared.js

@@ -0,0 +1,305 @@
+/**
+ * Shared route helpers and middleware factories.
+ *
+ * These utilities are injected into every route module via their
+ * `*RouteDependencies` interface so that no module needs to reach back into
+ * routes.ts at runtime.
+ */
+import { TaskforceRuleError } from '../../core/Taskforce.js';
+import { resolveRequestAccess, } from '../auth.js';
+// === SECTION: Error helpers ===
+export function resolveErrorStatusCode(error, fallback = 400) {
+    if (error instanceof TaskforceRuleError)
+        return error.statusCode;
+    const statusCode = Number(error?.statusCode);
+    if (Number.isFinite(statusCode) && statusCode >= 400 && statusCode <= 599) {
+        return statusCode;
+    }
+    return fallback;
+}
+// === SECTION: Request header helpers ===
+export function requestHeader(req, name, fallback = '') {
+    const value = req.headers?.[name.toLowerCase()];
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value) && value.length > 0)
+        return String(value[0]);
+    return fallback;
+}
+export function requestWorkspaceHeader(req) {
+    return requestHeader(req, 'x-taskforce-workspace-id', '').trim();
+}
+export function requestAuthoritativeWorkspaceId(req) {
+    const authoritative = requestHeader(req, 'x-taskforce-workspace-authoritative', '').trim().toLowerCase();
+    if (authoritative !== '1' && authoritative !== 'true')
+        return '';
+    return requestWorkspaceHeader(req);
+}
+export function requestRuntimeMode(req) {
+    const raw = String(requestHeader(req, 'x-taskforce-runtime-mode', '')).trim().toLowerCase();
+    return raw === 'cloud' ? 'cloud' : 'local';
+}
+export function requestRole(req) {
+    return requestHeader(req, 'x-taskforce-role', 'member');
+}
+export function requestSystemRole(req) {
+    const raw = requestHeader(req, 'x-taskforce-system-role', 'user').trim().toLowerCase();
+    return raw === 'system_admin' ? 'system_admin' : 'user';
+}
+export function requestUserId(req) {
+    return requestHeader(req, 'x-taskforce-user-id', 'anonymous') || 'anonymous';
+}
+// === SECTION: Workspace ID resolution ===
+export function makeRequestWorkspaceId(core, context) {
+    return function requestWorkspaceId(req) {
+        if (requestRuntimeMode(req) === 'local') {
+            try {
+                const urlObj = new URL(req.url || '/', 'http://localhost');
+                const urlWorkspaceId = urlObj.searchParams.get('workspaceId');
+                if (urlWorkspaceId && urlWorkspaceId.trim().length > 0) {
+                    return urlWorkspaceId.trim();
+                }
+            }
+            catch {
+                // Ignore URL parsing errors
+            }
+            return core.resolvePreferredWorkspaceId({ allowDefault: true }) || 'default';
+        }
+        const authConfig = context.authConfig;
+        if (authConfig?.enabled) {
+            const access = resolveRequestAccess(req, authConfig);
+            const sessionWorkspaceId = String(access.workspaceId || '').trim();
+            if (access.authenticated && access.userId && access.userId !== 'anonymous') {
+                const memberWorkspaces = core.listUserWorkspaces(access.userId);
+                const memberWorkspaceIds = new Set(memberWorkspaces.map((workspace) => String(workspace.id || '').trim()).filter(Boolean));
+                if (memberWorkspaceIds.size === 0)
+                    return 'default';
+                const requestedWorkspaceId = requestWorkspaceHeader(req);
+                const authoritativeWorkspaceId = requestAuthoritativeWorkspaceId(req);
+                if (authoritativeWorkspaceId) {
+                    const allowed = memberWorkspaceIds.has(authoritativeWorkspaceId);
+                    if (allowed)
+                        return authoritativeWorkspaceId;
+                }
+                if (requestedWorkspaceId) {
+                    const allowed = memberWorkspaceIds.has(requestedWorkspaceId);
+                    if (allowed && !sessionWorkspaceId)
+                        return requestedWorkspaceId;
+                }
+                if (sessionWorkspaceId && sessionWorkspaceId !== 'default' && memberWorkspaceIds.has(sessionWorkspaceId))
+                    return sessionWorkspaceId;
+                const resolvedWorkspaceId = core.resolvePreferredUserWorkspaceId(access.userId, {
+                    preferredWorkspaceId: requestedWorkspaceId || null,
+                    persistedWorkspaceId: sessionWorkspaceId || null
+                });
+                if (resolvedWorkspaceId)
+                    return resolvedWorkspaceId;
+                return 'default';
+            }
+            return 'default';
+        }
+        const requestedWorkspaceId = requestAuthoritativeWorkspaceId(req) || requestWorkspaceHeader(req);
+        if (requestedWorkspaceId) {
+            return requestedWorkspaceId;
+        }
+        return '';
+    };
+}
+// === SECTION: Authenticated user ID resolution ===
+export function makeResolveAuthenticatedUserId(core, context, requestWorkspaceId) {
+    return function resolveAuthenticatedUserId(req) {
+        const authConfig = context.authConfig;
+        if (authConfig?.enabled) {
+            const access = resolveRequestAccess(req, authConfig);
+            if (access.authenticated && access.userId && access.userId !== 'anonymous')
+                return access.userId;
+        }
+        const explicitUserId = String(requestUserId(req) || '').trim();
+        if (explicitUserId && explicitUserId !== 'anonymous')
+            return explicitUserId;
+        if (requestRuntimeMode(req) !== 'local')
+            return explicitUserId || 'anonymous';
+        const workspaceId = String(requestWorkspaceId(req) || '').trim() || 'default';
+        const fallbackUser = core.listWorkspaceUsers(workspaceId).find((user) => {
+            const status = String(user.status || '').trim().toLowerCase();
+            return status === 'active' && user.disabled !== true;
+        });
+        return String(fallbackUser?.userId || explicitUserId || 'anonymous').trim() || 'anonymous';
+    };
+}
+export function makeResolveAuthenticatedMutationUserId(core, context, requestWorkspaceId) {
+    return function resolveAuthenticatedMutationUserId(req) {
+        const authConfig = context.authConfig;
+        if (authConfig?.enabled) {
+            const access = resolveRequestAccess(req, authConfig);
+            if (access.authenticated && access.userId && access.userId !== 'anonymous')
+                return access.userId;
+        }
+        const explicitUserId = String(requestUserId(req) || '').trim();
+        if (explicitUserId && explicitUserId !== 'anonymous')
+            return explicitUserId;
+        if (requestRuntimeMode(req) === 'local') {
+            const workspaceId = String(requestWorkspaceId(req) || '').trim() || 'default';
+            const fallbackUser = core.listWorkspaceUsers(workspaceId).find((user) => {
+                const status = String(user.status || '').trim().toLowerCase();
+                return status === 'active' && user.disabled !== true;
+            });
+            const fallbackUserId = String(fallbackUser?.userId || '').trim();
+            if (fallbackUserId)
+                return fallbackUserId;
+        }
+        throw new TaskforceRuleError('Authenticated user required for mutation attribution.', 401, 'MUTATION_AUTH_REQUIRED');
+    };
+}
+// === SECTION: App access guard ===
+export function makeEnsureAppAccess(core, context) {
+    return function ensureAppAccess(req, res) {
+        if (requestRuntimeMode(req) !== 'cloud')
+            return true;
+        const authConfig = context.authConfig;
+        if (!authConfig?.enabled)
+            return true;
+        const access = resolveRequestAccess(req, authConfig);
+        if (!access.authenticated || !access.userId || access.userId === 'anonymous')
+            return true;
+        const accountAccess = core.getAccountAccessStatus(access.userId);
+        if (accountAccess.canAccessApp)
+            return true;
+        const code = accountAccess.gate === 'plan_selection_required'
+            ? 'PLAN_SELECTION_REQUIRED'
+            : accountAccess.gate === 'misconfigured'
+                ? 'ACCOUNT_ACCESS_MISCONFIGURED'
+                : 'ACCOUNT_ENTITLEMENT_REQUIRED';
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            error: accountAccess.message || 'This account cannot access the app.',
+            code,
+            gate: accountAccess.gate,
+            canAccessPlans: accountAccess.canAccessPlans,
+            planSelectionRequired: accountAccess.planSelectionRequired
+        }));
+        return false;
+    };
+}
+// === SECTION: Role guards ===
+export function makeEnsureAdminRole(core, context) {
+    return function ensureAdminRole(req) {
+        const actor = makeResolveAdminRequestActor(core, context)(req);
+        return actor.authenticated && actor.systemRole === 'system_admin';
+    };
+}
+export function makeEnsureAuthenticatedUser() {
+    return function ensureAuthenticatedUser(req) {
+        const userId = String(requestUserId(req) || '').trim();
+        return userId.length > 0 && userId !== 'anonymous';
+    };
+}
+export function ensureOwnerRole(req) {
+    return requestRole(req) === 'owner';
+}
+export function ensureWorkspaceAdminRole(req) {
+    const role = requestRole(req);
+    return role === 'owner' || role === 'admin';
+}
+// === SECTION: Admin actor resolution ===
+export function makeResolveAdminRequestActor(core, context) {
+    return function resolveAdminRequestActor(req) {
+        const authConfig = context.authConfig;
+        if (authConfig?.enabled) {
+            const access = resolveRequestAccess(req, authConfig);
+            if (access.authenticated && access.userId && access.userId !== 'anonymous') {
+                return {
+                    authenticated: true,
+                    userId: access.userId,
+                    systemRole: core.getSystemRole(access.userId)
+                };
+            }
+            return {
+                authenticated: false,
+                userId: 'anonymous',
+                systemRole: 'user'
+            };
+        }
+        const userId = String(requestUserId(req) || '').trim() || 'anonymous';
+        const systemRole = requestSystemRole(req);
+        return {
+            authenticated: systemRole === 'system_admin' || userId !== 'anonymous',
+            userId,
+            systemRole
+        };
+    };
+}
+// === SECTION: Audit helpers ===
+export function makeAuditAdminAction(core, context) {
+    const resolveAdminRequestActor = makeResolveAdminRequestActor(core, context);
+    return function auditAdminAction(req, action, details) {
+        const actor = resolveAdminRequestActor(req);
+        const payload = {
+            ts: new Date().toISOString(),
+            action,
+            actorUserId: actor.userId,
+            actorRole: actor.systemRole,
+            workspaceId: 'system',
+            details
+        };
+        try {
+            core.addAdminAuditLog({
+                action: payload.action,
+                actorUserId: payload.actorUserId,
+                actorRole: payload.actorRole,
+                workspaceId: payload.workspaceId,
+                details: payload.details
+            });
+        }
+        catch (error) {
+            console.warn(`[Taskforce Admin Audit] failed to persist log: ${String(error?.message || error)}`);
+        }
+        console.info(`[Taskforce Admin Audit] ${JSON.stringify(payload)}`);
+    };
+}
+export function makeAuditAuthAction(core, requestWorkspaceId) {
+    return function auditAuthAction(req, action, details) {
+        const payload = {
+            ts: new Date().toISOString(),
+            action,
+            actorUserId: requestUserId(req),
+            actorRole: requestRole(req),
+            workspaceId: requestWorkspaceId(req),
+            details
+        };
+        try {
+            core.addAdminAuditLog({
+                action: payload.action,
+                actorUserId: payload.actorUserId,
+                actorRole: payload.actorRole,
+                workspaceId: payload.workspaceId,
+                details: payload.details
+            });
+        }
+        catch (error) {
+            console.warn(`[Taskforce Auth Audit] failed to persist log: ${String(error?.message || error)}`);
+        }
+        console.info(`[Taskforce Auth Audit] ${JSON.stringify(payload)}`);
+    };
+}
+// === SECTION: Cloud runtime guard ===
+export function makeRequireCloudRuntime(context) {
+    return function requireCloudRuntime(res, feature) {
+        if (context.authConfig?.runtimeMode === 'cloud')
+            return true;
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `${feature} is only available in cloud runtime.` }));
+        return false;
+    };
+}
+// === SECTION: Cloud plan data guard ===
+export function makeEnsureCloudPlanData(context) {
+    return function ensureCloudPlanData(req, res) {
+        const runtime = context.authConfig?.runtimeMode || requestRuntimeMode(req);
+        if (runtime === 'cloud')
+            return true;
+        res.writeHead(409, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Plan and billing data are cloud-only.', code: 'CLOUD_PLAN_DATA_REQUIRED' }));
+        return false;
+    };
+}

package/dist/server/routes/shared.test.d.ts

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

package/dist/server/routes/shared.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from 'vitest';
+import { makeRequestWorkspaceId } from './shared.js';
+describe('makeRequestWorkspaceId', () => {
+    it('prefers explicit workspaceId query params in local mode', () => {
+        const core = {
+            resolvePreferredWorkspaceId: vi.fn().mockReturnValue('workspace-preferred')
+        };
+        const requestWorkspaceId = makeRequestWorkspaceId(core, {});
+        const req = {
+            url: '/api/taskforce/sync/workspace/ai-profiles?workspaceId=workspace-query',
+            headers: {
+                'x-taskforce-runtime-mode': 'local'
+            }
+        };
+        expect(requestWorkspaceId(req)).toBe('workspace-query');
+        expect(core.resolvePreferredWorkspaceId).not.toHaveBeenCalled();
+    });
+    it('falls back to preferred workspace when local query param is absent', () => {
+        const core = {
+            resolvePreferredWorkspaceId: vi.fn().mockReturnValue('workspace-preferred')
+        };
+        const requestWorkspaceId = makeRequestWorkspaceId(core, {});
+        const req = {
+            url: '/api/taskforce/sync/workspace/ai-profiles',
+            headers: {
+                'x-taskforce-runtime-mode': 'local'
+            }
+        };
+        expect(requestWorkspaceId(req)).toBe('workspace-preferred');
+        expect(core.resolvePreferredWorkspaceId).toHaveBeenCalledWith({ allowDefault: true });
+    });
+});

package/dist/server/{routes.sync.d.ts → routes/sync.d.ts}

@@ -1,11 +1,11 @@
 import { IncomingMessage } from 'http';
-import { TaskforceCore } from '../core/Taskforce.js';
-import { RouteHandler, RouteContext } from './routes.js';
-import { resolveRequestAccess, createSessionTokenCookie } from './auth.js';
-import { isReservedWorkspaceId } from '../utils/workspaceIdentity.js';
+import { TaskforceCore, TaskforceSyncCapable } from '../../core/Taskforce.js';
+import { RouteHandler, RouteContext } from '../routes.js';
+import { resolveRequestAccess, createSessionTokenCookie } from '../auth.js';
+import { isReservedWorkspaceId } from '../../utils/workspaceIdentity.js';
 export interface SyncRouteDependencies {
     addRoute: (method: string, path: string, handler: RouteHandler) => void;
-    core: TaskforceCore;
+    core: TaskforceCore & TaskforceSyncCapable;
     context: RouteContext;
     auditAuthAction: (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
     resolveErrorStatusCode: (error: unknown, fallback?: number) => number;

package/dist/server/routes/sync.integration.test.d.ts

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