@we-scrum/cli 1.0.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@we-scrum/cli",
+  "version": "1.0.0",
+  "description": "Cli tool for we-scrum application",
+  "main": "dist/cli.js",
+  "bin": {
+    "we-scrum": "dist/cli.js"
+  },
+  "tsup": {
+    "entry": [
+      "src/cli.ts"
+    ],
+    "format": [
+      "cjs"
+    ],
+    "clean": true,
+    "minify": true,
+    "bundle": true,
+    "keepNames": true,
+    "noExternal": [
+      "@we-scrum/*",
+      "@my-devkit/*"
+    ]
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "commander": "^11.1.0",
+    "firebase": "12.10.0",
+    "google-auth-library": "^10.6.1",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.18.6",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "@my-devkit/cli": "2.1.0",
+    "@my-devkit/core": "1.0.0",
+    "@we-scrum/enums": "1.0.0",
+    "@we-scrum/models": "1.0.0",
+    "@we-scrum/commands": "1.0.0"
+  },
+  "scripts": {
+    "build": "mdk build",
+    "watch": "mdk watch",
+    "build:prod": "tsup",
+    "publish:public": "pnpm publish --access public",
+    "preinstall": "npx only-allow pnpm",
+    "global:link": "pnpm link --global",
+    "global:unlink": "pnpm remove --global @we-scrum/cli"
+  }
+}

package/src/auth-helper.ts

@@ -0,0 +1,107 @@
+import { Logger } from '@my-devkit/core';
+import { GoogleAuthProvider, signInWithCredential, User } from 'firebase/auth';
+import { CodeChallengeMethod, OAuth2Client } from 'google-auth-library';
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import open from 'open';
+
+import { FirebaseHelper } from './firebase-helper';
+import { SettingsHelper } from './settings-helper';
+
+export class AuthHelper {
+    // 2. Google OAuth2 Config
+    private static cid = '847201088225-vi6fq1rjoouoe24ac9oalst4nis0r597.apps.googleusercontent.com';
+    private static csec = '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'; // Note: This is a Public Client Secret for a CLI tool, safe to expose per RFC 8252.
+    private static PORT = 3000;
+    private static REDIRECT_URI = `http://localhost:${this.PORT}`;
+    public static get userId(): string {
+        return FirebaseHelper.auth.currentUser?.uid;
+    }
+
+    public static async loginWithGoogle(): Promise<User> {
+        const auth = FirebaseHelper.auth;
+
+        const { verifier, challenge } = this.generatePKCE();
+        const oAuth2Client = new OAuth2Client(this.cid, this.csec, this.REDIRECT_URI);
+
+        return new Promise((resolve, reject) => {
+            // Create a temporary local server to catch the redirect
+            const server = createServer(async (req, res) => {
+                try {
+                    const url = new URL(req.url, this.REDIRECT_URI);
+                    const code = url.searchParams.get('code');
+
+                    if (code) {
+                        // Send a friendly message to the browser
+                        res.writeHead(200, { 'Content-Type': 'text/html' });
+                        res.end('<h1>Login Successful!</h1><p>You can close this tab and return to the terminal.</p>');
+
+                        // Stop listening
+                        server.close();
+
+                        // Exchange the Authorization Code for tokens using the PKCE Verifier
+                        const { tokens } = await oAuth2Client.getToken({
+                            code: code,
+                            codeVerifier: verifier,
+                        });
+
+                        // Persist credentials in settings
+                        SettingsHelper.set({ credentials: tokens });
+
+                        // Build Firebase credential and sign in
+                        const credential = GoogleAuthProvider.credential(tokens.id_token);
+
+                        const userCredential = await signInWithCredential(auth, credential);
+
+                        resolve(userCredential.user);
+                    }
+                } catch (err) {
+                    res.end('Authentication failed.');
+                    server.close();
+                    reject(err);
+                }
+            });
+
+            server.listen(this.PORT, () => {
+                // 4. Generate the Auth URL with the PKCE Challenge
+                const authUrl = oAuth2Client.generateAuthUrl({
+                    access_type: 'offline', // Required to get a refresh_token
+                    scope: ['openid', 'email', 'profile'],
+                    code_challenge: challenge,
+                    code_challenge_method: CodeChallengeMethod.S256,
+                });
+
+                Logger.info('Opening your browser for authentication...');
+                open(authUrl);
+            });
+        });
+    }
+
+    /**
+     * Generates PKCE Verifier and Challenge
+     */
+    private static generatePKCE() {
+        const verifier = randomBytes(32).toString('base64url');
+        const challenge = createHash('sha256').update(verifier).digest('base64url');
+        return { verifier, challenge };
+    }
+
+    public static logout() {
+        SettingsHelper.set({ credentials: undefined });
+    }
+
+    public static async initializeFromStoredCredentials(): Promise<boolean> {
+        const credentials = SettingsHelper.get().credentials ?? null;
+        if (!credentials?.id_token) {
+            return false;
+        }
+        try {
+            const auth = FirebaseHelper.auth;
+            const credential = GoogleAuthProvider.credential(credentials.id_token);
+            await signInWithCredential(auth, credential);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+}

package/src/cli.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { select } from '@inquirer/prompts';
+import { Logger } from '@my-devkit/core';
+import { UserProjectModel } from '@we-scrum/models';
+import { Command } from 'commander';
+
+import { AuthHelper } from './auth-helper';
+import { FirebaseHelper } from './firebase-helper';
+import { startMcpServer } from './mcp-server';
+import { SettingsHelper } from './settings-helper';
+
+Logger.registerLogger(new Logger.ConsoleImplementation());
+
+const program = new Command();
+
+program.name('we-scrum').description('CLI for we-scrum application').version('1.0.0');
+
+program
+    .command('login')
+    .description('Authenticate with your Google account')
+    .action(async () => {
+        try {
+            await AuthHelper.loginWithGoogle();
+            process.exit(0);
+        } catch (error) {
+            Logger.error(error?.message ?? 'Login failed');
+            process.exit(1);
+        }
+    });
+
+program
+    .command('logout')
+    .description('Log out and remove stored credentials')
+    .action(() => {
+        AuthHelper.logout();
+        Logger.info('Logged out successfully.');
+        process.exit(0);
+    });
+
+program
+    .command('use-project')
+    .description('Select the active project')
+    .option('--projectId <id>', 'Set the active project directly without the interactive prompt')
+    .action(async (options: { projectId?: string }) => {
+        try {
+            const initialized = await AuthHelper.initializeFromStoredCredentials();
+            if (!initialized) {
+                Logger.error('Not authenticated. Please run "we-scrum login" first.');
+                process.exit(1);
+            }
+
+            const projects = await FirebaseHelper.getCollection<UserProjectModel>(`users/${AuthHelper.userId}/projects`);
+            if (projects.length === 0) {
+                Logger.error('No projects found for your account.');
+                process.exit(1);
+            }
+
+            let selectedProjectId: string;
+
+            if (options.projectId) {
+                const match = projects.find((p) => p.projectId === options.projectId);
+                if (!match) {
+                    Logger.error(`Project "${options.projectId}" not found in your account.`);
+                    process.exit(1);
+                }
+                selectedProjectId = match.projectId;
+            } else {
+                selectedProjectId = await select({
+                    message: 'Select a project',
+                    default: SettingsHelper.get().selectedProjectId,
+                    choices: projects.map((p) => ({
+                        name: p.name,
+                        value: p.projectId,
+                        description: p.projectId,
+                    })),
+                });
+            }
+
+            SettingsHelper.set({ selectedProjectId });
+            Logger.info(`Active project set to: ${projects.find((p) => p.projectId === selectedProjectId)?.name}`);
+            process.exit(0);
+        } catch (error) {
+            if (error?.name === 'ExitPromptError') {
+                process.exit(0);
+            }
+            Logger.error(error?.message ?? 'Failed to select project');
+            process.exit(1);
+        }
+    });
+
+program
+    .command('mcp')
+    .description('Start the we-scrum MCP server (stdio transport)')
+    .option('--projectId <id>', 'Override the active project for this session')
+    .action(async (options: { projectId?: string }) => {
+        if (options.projectId) {
+            SettingsHelper.set({ selectedProjectId: options.projectId });
+        }
+        await startMcpServer();
+    });
+
+program.parse(process.argv);

package/src/firebase-helper.ts

@@ -0,0 +1,129 @@
+import { deserialize } from '@my-devkit/core';
+import * as models from '@we-scrum/models';
+import { FirebaseApp, initializeApp } from 'firebase/app';
+import { Auth, getAuth } from 'firebase/auth';
+import {
+    DocumentData,
+    FieldPath,
+    Firestore,
+    OrderByDirection,
+    Query,
+    QueryCompositeFilterConstraint,
+    QueryNonFilterConstraint,
+    WhereFilterOp,
+    and,
+    collection,
+    doc,
+    getDoc,
+    getDocs,
+    getFirestore,
+    limit,
+    orderBy,
+    query,
+    where,
+} from 'firebase/firestore';
+
+for (const i in models) {
+    new models[i]();
+}
+
+export class FirebaseHelper {
+    private static _app: FirebaseApp;
+    private static _auth: Auth;
+    private static _firestore: Firestore;
+
+    public static get auth(): Auth {
+        if (!this._auth) {
+            this._auth = getAuth(FirebaseHelper.app);
+        }
+
+        return this._auth;
+    }
+
+    public static async getCollection<T>(path: string, options?: FirebaseHelper.Query): Promise<T[]> {
+        const q = this.query(path, options);
+
+        const documents = await getDocs(q);
+
+        return documents.docs.map((doc) => deserialize<T>(doc.data()));
+    }
+
+    public static async findDocument<T>(path: string, where: FirebaseHelper.Where[]): Promise<T> {
+        const documents = await this.getCollection<T>(path, { where });
+
+        if (documents.length === 0) {
+            return null;
+        }
+
+        if (documents.length > 1) {
+            throw new Error(`More than one document found at ${path} where ${where.map((w) => JSON.stringify(w)).join(' AND ')}`);
+        }
+
+        return documents[0];
+    }
+
+    public static async getDocument<T>(path: string): Promise<T | null> {
+        const docRef = doc(this.firestore, path);
+        const docSnapshot = await getDoc(docRef);
+
+        if (!docSnapshot.exists()) {
+            throw new Error(`Document ${path} not found`);
+        }
+
+        return deserialize<T>(docSnapshot.data());
+    }
+
+    private static get app() {
+        if (!this._app) {
+            // Should depend on targeted environment
+            const firebaseConfig = {
+                apiKey: 'AIzaSyCodItNw1wtWfx1GAU_x0Pj96mCAUyrWvU',
+                authDomain: 'we-scrum-prod.firebaseapp.com',
+                projectId: 'we-scrum-prod',
+            };
+
+            this._app = initializeApp(firebaseConfig);
+        }
+
+        return this._app;
+    }
+
+    private static get firestore() {
+        if (!this._firestore) {
+            this._firestore = getFirestore(this.app);
+        }
+
+        return this._firestore;
+    }
+
+    private static query(path: string, options?: FirebaseHelper.Query): Query<DocumentData, DocumentData> {
+        const ref = collection(this.firestore, path);
+
+        let filter: QueryCompositeFilterConstraint;
+        if (options?.where) {
+            filter = and(...options.where.map((w) => where(...w)));
+        }
+
+        const constraints: QueryNonFilterConstraint[] = [];
+        if (options?.orderBy) {
+            constraints.push(orderBy(...options.orderBy));
+        }
+
+        if (options?.limit) {
+            constraints.push(limit(options.limit));
+        }
+
+        return query(ref, filter, ...constraints);
+    }
+}
+
+export namespace FirebaseHelper {
+    export interface Query {
+        where?: Where[];
+        orderBy?: OrderBy;
+        limit?: number;
+    }
+
+    export type Where = [string | FieldPath, opStr: WhereFilterOp, value: unknown];
+    type OrderBy = [string | FieldPath, OrderByDirection?];
+}

package/src/mcp-server.ts

@@ -0,0 +1,127 @@
+import { Server } from '@modelcontextprotocol/sdk/server';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ProgressStatus } from '@we-scrum/enums';
+import { ProjectStoryModel, ProjectStorySectionModel } from '@we-scrum/models';
+
+import { AuthHelper } from './auth-helper';
+import { FirebaseHelper } from './firebase-helper';
+import { SettingsHelper } from './settings-helper';
+
+const TOOLS = [
+    {
+        name: 'get_next_task',
+        description: `Get the next pending task (status: ToDo) for a story.
+Returns the task description, the task type template (development guidelines),
+and the full section analysis specifying what must be implemented
+(route changes, object/DTO changes, enumeration changes, relation/handler changes).
+Also returns storyId, sectionId and taskId needed to call start_task and complete_task.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                identificationNumber: {
+                    type: 'string',
+                    description: 'The story identification number, e.g. "144154"',
+                },
+            },
+            required: ['identificationNumber'],
+        },
+    },
+];
+
+async function handleGetNextTask(identificationNumber: string): Promise<string> {
+    const projectId = SettingsHelper.get().selectedProjectId;
+    if (!projectId) {
+        throw new Error('No active project selected. Please run "we-scrum use-project" first.');
+    }
+
+    // 1. Find story by identificationNumber
+    const story = await FirebaseHelper.findDocument<ProjectStoryModel>(`/projects/${projectId}/stories`, [
+        ['identificationNumber', '==', identificationNumber],
+    ]);
+
+    if (!story) {
+        throw new Error(`Story "${identificationNumber}" not found in the active project.`);
+    }
+
+    // 2. Fetch all section documents at once
+    const sections = await FirebaseHelper.getCollection<ProjectStorySectionModel>(
+        `projects/${projectId}/stories/${story.storyId}/sections`,
+    );
+
+    // 3. Order sections using the position stored in story.sections[]
+    const positionBySection = new Map(story.sections.map((s) => [s.sectionId, s.position ?? 0]));
+    const sortedSections = sections.sort((a, b) => (positionBySection.get(a.sectionId) ?? 0) - (positionBySection.get(b.sectionId) ?? 0));
+
+    // 4. Walk sections in order and find the first ToDo task
+    for (const section of sortedSections) {
+        const tasks = [...(section.tasks ?? [])].sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+        const nextTask = tasks.find((t) => t.progress?.status === ProgressStatus.ToDo);
+
+        if (!nextTask) continue;
+
+        const result = {
+            storyId: story.storyId,
+            storyName: story.name,
+            sectionId: section.sectionId,
+            sectionName: section.name,
+            task: {
+                taskId: nextTask.taskId,
+                description: nextTask.description,
+                taskTypeName: nextTask.taskTypeName,
+                position: nextTask.position,
+                status: nextTask.progress?.status,
+            },
+            sectionAnalysis: {
+                ...(section.routeChanges?.length && { routeChanges: section.routeChanges }),
+                ...(section.objectChanges?.length && { objectChanges: section.objectChanges }),
+                ...(section.enumerationChanges?.length && { enumerationChanges: section.enumerationChanges }),
+                ...(section.relationChanges?.length && { relationChanges: section.relationChanges }),
+            },
+        };
+
+        return JSON.stringify(result, null, 2);
+    }
+
+    return JSON.stringify({ message: `All tasks for story "${identificationNumber}" are complete.` });
+}
+
+export async function startMcpServer(): Promise<void> {
+    const initialized = await AuthHelper.initializeFromStoredCredentials();
+    if (!initialized) {
+        process.stderr.write('Error: Not authenticated. Please run "we-scrum login" first.\n');
+        process.exit(1);
+    }
+
+    const server = new Server({ name: 'we-scrum-mcp-server', version: '1.0.0' }, { capabilities: { tools: {} } });
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+
+        try {
+            let text: string;
+
+            switch (name) {
+                case 'get_next_task':
+                    text = await handleGetNextTask(args.identificationNumber as string);
+                    break;
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+
+            return { content: [{ type: 'text', text }] };
+        } catch (error) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    process.stderr.write('we-scrum MCP server running.\n');
+}

package/src/settings-helper.ts

@@ -0,0 +1,35 @@
+import { JsonHelper } from '@my-devkit/core';
+import { Credentials } from 'google-auth-library';
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join as pathJoin } from 'node:path';
+
+const SETTINGS_FILE = pathJoin(homedir(), '.we-scrum.json');
+
+export interface WeScrumSettings {
+    credentials?: Credentials;
+    selectedProjectId?: string;
+}
+
+export class SettingsHelper {
+    public static get(): WeScrumSettings {
+        if (!existsSync(SETTINGS_FILE)) {
+            return {};
+        }
+        const content = readFileSync(SETTINGS_FILE, 'utf8');
+        return JsonHelper.parse<WeScrumSettings>(content) ?? {};
+    }
+
+    public static set(partial: Partial<WeScrumSettings>): void {
+        const updated = { ...this.get(), ...partial };
+
+        writeFileSync(SETTINGS_FILE, JSON.stringify(updated, null, 2));
+        chmodSync(SETTINGS_FILE, 0o600);
+    }
+
+    public static clear(): void {
+        if (existsSync(SETTINGS_FILE)) {
+            rmSync(SETTINGS_FILE);
+        }
+    }
+}

package/src/we-scrum.service.ts

@@ -0,0 +1,107 @@
+import { Command, serialize } from '@my-devkit/core';
+
+export class WeScrumService {
+    constructor(
+        private backendUrl: string,
+        private projectId: string,
+        private userId: string,
+    ) {}
+
+    // public async createEnumeration(enumeration: Enumeration): Promise<string> {
+    //     Logger.info(`Creating enumeration ${enumeration.name}`);
+
+    //     const createCommand = TypeHelper.transform(CreateEnumerationCommand, {
+    //         projectId: this.projectId,
+    //         name: enumeration.name,
+    //     });
+
+    //     const enumerationId = await this.post<CreateEnumerationCommand, string>('enumeration-management/create-enumeration', createCommand);
+    //     for (const property of enumeration.properties) {
+    //         const propertyCommand = TypeHelper.transform(CreateEnumerationPropertyCommand, {
+    //             enumerationId,
+    //             enumerationPropertyId: guid(),
+    //             name: property.label,
+    //             value: property.value,
+    //         });
+    //         await this.post<CreateEnumerationPropertyCommand, string>(
+    //             'enumeration-management/create-enumeration-property',
+    //             propertyCommand,
+    //         );
+    //     }
+
+    //     return enumerationId;
+    // }
+
+    // public async createObject(object: Object, getEnumerationId: (name: string) => string): Promise<string> {
+    //     Logger.info(`Creating object ${object.name}`);
+
+    //     const createCommand = TypeHelper.transform(CreateObjectCommand, {
+    //         projectId: this.projectId,
+    //         name: object.name,
+    //     });
+    //     const objectId = await this.post<CreateObjectCommand, string>('object-management/create-object', createCommand);
+
+    //     const propertyMap = new Map<string, string>();
+    //     for (const property of object.properties) {
+    //         const objectPropertyId = guid();
+    //         const propertyCommand = TypeHelper.transform(CreateObjectPropertyCommand, {
+    //             objectId,
+    //             objectPropertyId,
+    //             objectPropertyParentId: propertyMap.get(property.parent) || null,
+    //             name: property.name,
+    //             objectPropertyType: property.type,
+    //             isArray: property.isArray,
+    //             enumerationId: property.enumerationName ? getEnumerationId(property.enumerationName) : null,
+    //         });
+    //         await this.post<CreateObjectPropertyCommand, string>('object-management/create-object-property', propertyCommand);
+
+    //         propertyMap.set(property.path, objectPropertyId);
+    //     }
+
+    //     return objectId;
+    // }
+
+    // public async createHandler(handler: Handler, getObjectId: (name: string) => string): Promise<void> {
+    //     Logger.info(`Creating handler ${handler.name}`);
+
+    //     for (const relation of handler.relations) {
+    //         const createCommand = TypeHelper.transform(CreateRelationCommand, {
+    //             projectId: this.projectId,
+    //             boundedContext: handler.boundedContext,
+    //             handlerName: handler.name,
+    //             objectIds: relation.map((o) => getObjectId(o)),
+    //             subscriptionName: null,
+    //         });
+    //         await this.post<CreateRelationCommand, string>('relation-management/create-relation', createCommand);
+    //     }
+    // }
+
+    // public async createRoute(route: Route, getObjectId: (name: string) => string): Promise<string> {
+    //     Logger.info(`Creating route ${route.method} ${route.path}`);
+
+    //     const createCommand = TypeHelper.transform(CreateRouteCommand, {
+    //         projectId: this.projectId,
+    //         method: route.method,
+    //         path: route.path,
+    //         objectId: getObjectId(route.object),
+    //         permission: null,
+    //     });
+
+    //     return this.post<CreateRouteCommand, string>('route-management/create-route', createCommand);
+    // }
+
+    private async post<C extends Command, R>(route: string, command: C): Promise<R> {
+        const response = await fetch(`${this.backendUrl}/command/${route}`, {
+            method: 'POST',
+            body: JSON.stringify(serialize(command)),
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: 'Basic ' + Buffer.from(`${this.userId}:20V0anV4M!we`).toString('base64'),
+            },
+            signal: AbortSignal.timeout(60 * 1000),
+        });
+
+        const body = (await response.json()) as { result: R };
+        return body.result;
+    }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "moduleResolution": "node",
+        "target": "es2021",
+        "outDir": "./dist",
+        "baseUrl": "src",
+        "sourceMap": true,
+        "declaration": false,
+        "emitDecoratorMetadata": true,
+        "experimentalDecorators": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "paths": {
+            "@modelcontextprotocol/sdk/server": ["../node_modules/@modelcontextprotocol/sdk/dist/esm/server/index"],
+            "@modelcontextprotocol/sdk/server/stdio.js": ["../node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio"],
+            "@modelcontextprotocol/sdk/types.js": ["../node_modules/@modelcontextprotocol/sdk/dist/esm/types"]
+        }
+    }
+}