@we-scrum/cli 1.0.4 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@we-scrum/cli",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Cli tool for we-scrum application",
   "main": "dist/cli.js",
   "bin": {
@@ -20,27 +20,31 @@
     "noExternal": [
       "@we-scrum/*",
       "@my-devkit/*"
-    ]
+    ],
+    "loader": {
+      ".hbs": "text"
+    }
   },
   "dependencies": {
-    "@inquirer/prompts": "8.3.0",
-    "zod": "4.3.6",
-    "@modelcontextprotocol/sdk": "1.27.1",
-    "commander": "14.0.3",
-    "firebase": "12.10.0",
-    "google-auth-library": "^10.6.1",
-    "open": "^11.0.0"
+    "@inquirer/prompts": "^8.4.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.3",
+    "firebase": "^12.12.1",
+    "google-auth-library": "^10.6.2",
+    "handlebars": "^4.7.9",
+    "open": "^11.0.0",
+    "zod": "^4.4.1"
   },
   "devDependencies": {
-    "@types/node": "22.18.6",
-    "@modelcontextprotocol/inspector": "0.21.1",
-    "tsup": "8.5.1",
-    "typescript": "5.9.3",
+    "@modelcontextprotocol/inspector": "^0.21.2",
+    "@types/node": "^22.19.17",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
     "@my-devkit/cli": "2.1.0",
     "@my-devkit/core": "1.0.0",
     "@we-scrum/commands": "1.0.0",
-    "@we-scrum/enums": "1.0.0",
     "@we-scrum/models": "1.0.0",
+    "@we-scrum/enums": "1.0.0",
     "@we-scrum/utils": "1.0.0"
   },
   "scripts": {

package/src/cli.ts

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { select } from '@inquirer/prompts';
-import { Logger } from '@my-devkit/core';
+import { assert, Logger } from '@my-devkit/core';
 import { UserProjectModel } from '@we-scrum/models';
 import { Command } from 'commander';
 import { version } from '../package.json';
 
-import { AuthHelper, FirebaseHelper, SettingsHelper } from './helpers';
+import { AuthHelper, FirebaseHelper, SettingsHelper, WeScrumHelper } from './helpers';
 import { startMcpServer } from './mcp-server';
 
 Logger.registerLogger(new Logger.ConsoleImplementation());
@@ -14,54 +14,59 @@ const program = new Command();
 
 program.name('we-scrum').description('CLI for we-scrum application').version(version);
 
-program
-    .command('login')
-    .description('Authenticate with your Google account')
-    .action(async () => {
+async function requireAuth(): Promise<void> {
+    const initialized = await AuthHelper.initializeFromStoredCredentials();
+    assert(initialized, 'Not authenticated. Please run "we-scrum login" first.');
+}
+
+function runCommand<T = void>(fn: (options: T) => Promise<void>) {
+    return async (options: T) => {
         try {
-            await AuthHelper.loginWithGoogle();
+            await fn(options);
             process.exit(0);
         } catch (error) {
-            Logger.error(error?.message ?? 'Login failed');
+            if (error?.name === 'ExitPromptError') process.exit(0);
+            Logger.error(error?.message ?? 'Command failed');
             process.exit(1);
         }
-    });
+    };
+}
+
+program
+    .command('login')
+    .description('Authenticate with your Google account')
+    .action(
+        runCommand(async () => {
+            await AuthHelper.loginWithGoogle();
+        }),
+    );
 
 program
     .command('logout')
     .description('Log out and remove stored credentials')
-    .action(() => {
-        AuthHelper.logout();
-        Logger.info('Logged out successfully.');
-        process.exit(0);
-    });
+    .action(
+        runCommand(async () => {
+            AuthHelper.logout();
+            Logger.info('Logged out successfully.');
+        }),
+    );
 
 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);
-            }
+    .action(
+        runCommand<{ projectId?: string }>(async (options) => {
+            await requireAuth();
 
             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);
-            }
+            assert(projects.length > 0, 'No projects found for your account. Please create a project in the we-scrum web app first.');
 
             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);
-                }
+                assert(!!match, `Project "${options.projectId}" not found in your account.`);
                 selectedProjectId = match.projectId;
             } else {
                 selectedProjectId = await select({
@@ -77,15 +82,45 @@ program
 
             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('start-task')
+    .description('Mark a specific task as in progress')
+    .requiredOption('--identificationNumber <id>', 'Story identification number')
+    .requiredOption('--taskId <id>', 'Unique identifier of the change to act on')
+    .action(
+        runCommand<{ identificationNumber: string; taskId: string }>(async (options) => {
+            await requireAuth();
+            await WeScrumHelper.startTask(options.identificationNumber, options.taskId);
+            Logger.info('Task started successfully. You can now make changes to the codebase.');
+        }),
+    );
+
+program
+    .command('complete-task')
+    .description('Mark the current in-progress task as done')
+    .requiredOption('--identificationNumber <id>', 'Story identification number')
+    .requiredOption('--taskId <id>', 'Unique identifier of the change to act on')
+    .action(
+        runCommand<{ identificationNumber: string; taskId: string }>(async (options) => {
+            await requireAuth();
+            await WeScrumHelper.completeTask(options.identificationNumber, options.taskId);
+            Logger.info('Task completed successfully.');
+        }),
+    );
+
+program
+    .command('synchronize-development-policies')
+    .description('Sync development guidelines from we-scrum into .claude/')
+    .action(
+        runCommand(async () => {
+            await requireAuth();
+            const count = await WeScrumHelper.synchronizeDevelopmentPolicies(process.cwd());
+            Logger.info(`Synchronized ${count} development ${count === 1 ? 'policy' : 'policies'}.`);
+        }),
+    );
 
 program
     .command('mcp')

package/src/hbs.d.ts

@@ -0,0 +1,4 @@
+declare module '*.hbs' {
+    const content: string;
+    export default content;
+}

package/src/helpers/auth-helper.ts

@@ -70,7 +70,7 @@ export class AuthHelper {
 
                         // Exchange the Authorization Code for tokens using the PKCE Verifier
                         const { tokens } = await oAuth2Client.getToken({
-                            code: code,
+                            code,
                             codeVerifier: verifier,
                         });
 

package/src/helpers/index.ts

@@ -1,4 +1,5 @@
 export * from './auth-helper';
 export * from './firebase-helper';
 export * from './settings-helper';
+export * from './template.helper';
 export * from './we-scrum.helper';

package/src/helpers/template.helper.ts

@@ -0,0 +1,23 @@
+import Handlebars from 'handlebars';
+import getNextTaskDescription from '../../templates/get-next-task-description.hbs';
+import getNextTask from '../../templates/get-next-task.hbs';
+
+const sources = {
+    'get-next-task': getNextTask,
+    'get-next-task-description': getNextTaskDescription,
+} as const;
+
+export type TemplateName = keyof typeof sources;
+
+const compiled = new Map<TemplateName, Handlebars.TemplateDelegate>();
+
+function getTemplate(name: TemplateName): Handlebars.TemplateDelegate {
+    if (!compiled.has(name)) {
+        compiled.set(name, Handlebars.compile(sources[name]));
+    }
+    return compiled.get(name)!;
+}
+
+export function renderTemplate(name: TemplateName, context?: Record<string, unknown>): string {
+    return getTemplate(name)(context ?? {}).trim();
+}

package/src/helpers/we-scrum.helper.ts

@@ -1,4 +1,4 @@
-import { _sortBy, Command, serialize, TypeHelper } from '@my-devkit/core';
+import { _sortBy, assert, Command, serialize, TypeHelper } from '@my-devkit/core';
 import {
     MarkEnumerationChangeAsDoneCommand,
     MarkObjectChangeAsDoneCommand,
@@ -23,13 +23,16 @@ import {
     ProjectStorySectionModelTask,
 } from '@we-scrum/models';
 import { DevelopmentPolicyHelper } from '@we-scrum/utils';
-import { assert } from 'node:console';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { AuthHelper } from './auth-helper';
 import { FirebaseHelper } from './firebase-helper';
 import { SettingsHelper } from './settings-helper';
 
 export class WeScrumHelper {
-    private static backendUrl = 'https://europe-west1-we-scrum-prod.cloudfunctions.net';
+    private static readonly backendUrl = 'https://europe-west1-we-scrum-prod.cloudfunctions.net';
+    private static readonly claudeSubdir = '.claude';
+    private static readonly relPoliciesDir = `${WeScrumHelper.claudeSubdir}/development-policies`;
     constructor(private userId: string) {}
 
     public static get projectId(): string {
@@ -56,11 +59,33 @@ export class WeScrumHelper {
         return task;
     }
 
-    public static async startTask(identificationNumber: string): Promise<void> {
-        const change = await this.getNextChange(identificationNumber);
+    public static async getChangeById(identificationNumber: string, changeId: string) {
+        this.assertProjectIsSelected();
+
+        const story = await this.findStoryByIterationNumber(identificationNumber);
+        assert(!!story, `Story "${identificationNumber}" not found in the active project.`);
 
-        assert(!!change, `All tasks for story "${identificationNumber}" are complete.`);
-        assert(change.progress.status === ProgressStatus.ToDo, `Task is already in progress (current status: ${change.progress.status}).`);
+        const sections = await this.getStorySections(story.storyId);
+
+        const change = _sortBy(sections, (s) => s.name)
+            .flatMap((s) => [...s.enumerationChanges, ...s.objectChanges, ...s.routeChanges, ...s.relationChanges, ...s.tasks])
+            .find((t) => {
+                if (t instanceof ProjectStorySectionModelEnumerationChange) return t.enumerationChangeId === changeId;
+                if (t instanceof ProjectStorySectionModelObjectChange) return t.objectChangeId === changeId;
+                if (t instanceof ProjectStorySectionModelRouteChange) return t.routeChangeId === changeId;
+                if (t instanceof ProjectStorySectionModelRelationChange) return t.relationChangeId === changeId;
+                if (t instanceof ProjectStorySectionModelTask) return t.taskId === changeId;
+                return false;
+            });
+
+        assert(!!change, `Change "${changeId}" not found in story "${identificationNumber}".`);
+        return change;
+    }
+
+    public static async startTask(identificationNumber: string, taskId: string): Promise<void> {
+        const change = await this.getChangeById(identificationNumber, taskId);
+
+        assert(change.progress.status === ProgressStatus.ToDo, `Task is not in ToDo status (current status: ${change.progress.status}).`);
 
         if (change instanceof ProjectStorySectionModelEnumerationChange) {
             await this.post(
@@ -87,10 +112,9 @@ export class WeScrumHelper {
         }
     }
 
-    public static async completeTask(identificationNumber: string): Promise<void> {
-        const change = await this.getNextChange(identificationNumber);
+    public static async completeTask(identificationNumber: string, taskId: string): Promise<void> {
+        const change = await this.getChangeById(identificationNumber, taskId);
 
-        assert(!!change, `All tasks for story "${identificationNumber}" are complete.`);
         assert(change.progress.status === ProgressStatus.Doing, `Task is not in progress (current status: ${change.progress.status}).`);
 
         if (change instanceof ProjectStorySectionModelEnumerationChange) {
@@ -124,6 +148,20 @@ export class WeScrumHelper {
         return DevelopmentPolicyHelper.getMatchingDevelopmentPolicy(change, developmentPolicies);
     }
 
+    public static getDevelopmentPolicyPaths(
+        policy: DevelopmentPolicyModel | null,
+        projectDir = '.',
+    ): {
+        guidelinesPath: string | null;
+        unitTestsPath: string | null;
+    } {
+        const policiesDir = join(projectDir, this.relPoliciesDir);
+        return {
+            guidelinesPath: policy?.slug ? join(policiesDir, `develop-${policy.slug}.md`) : null,
+            unitTestsPath: policy?.slug ? join(policiesDir, `test-${policy.slug}.md`) : null,
+        };
+    }
+
     private static async findStoryByIterationNumber(identificationNumber: string) {
         return FirebaseHelper.findDocument<ProjectStoryModel>(`/projects/${this.projectId}/stories`, [
             ['identificationNumber', '==', identificationNumber],
@@ -134,92 +172,38 @@ export class WeScrumHelper {
         return FirebaseHelper.getCollection<ProjectStorySectionModel>(`projects/${this.projectId}/stories/${storyId}/sections`);
     }
 
-    private static async getDevelopmentPolicies() {
+    public static async getDevelopmentPolicies() {
         return FirebaseHelper.getCollection<DevelopmentPolicyModel>(`/projects/${this.projectId}/development-policies`);
     }
 
-    // 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);
-    // }
+    public static async synchronizeDevelopmentPolicies(projectDir: string): Promise<number> {
+        this.assertProjectIsSelected();
+
+        const claudeDir = join(projectDir, this.claudeSubdir);
+        assert(
+            existsSync(claudeDir),
+            `No ${this.claudeSubdir} directory found in ${projectDir}. Please run this command from the root of your project.`,
+        );
+
+        const policiesDir = join(projectDir, this.relPoliciesDir);
+
+        rmSync(policiesDir, { recursive: true, force: true });
+        mkdirSync(policiesDir, { recursive: true });
+
+        const policies = await this.getDevelopmentPolicies();
+
+        for (const policy of policies) {
+            const { guidelinesPath, unitTestsPath } = this.getDevelopmentPolicyPaths(policy, projectDir);
+            if (policy.codeGuidelines && guidelinesPath) {
+                writeFileSync(guidelinesPath, policy.codeGuidelines);
+            }
+            if (policy.unitTestsGuidelines && unitTestsPath) {
+                writeFileSync(unitTestsPath, policy.unitTestsGuidelines);
+            }
+        }
+
+        return policies.length;
+    }
 
     private static async post<C extends Command, R>(route: string, command: C): Promise<R> {
         const userIdToken = await AuthHelper.getUserIdToken();

package/src/mcp-server/mcp-server.ts

@@ -1,29 +1,23 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { z } from 'zod';
 
-import { AuthHelper } from '@helpers';
-import { completeTask, getNextTask, getUnitTestGuidelines, startTask } from './tools';
+import { AuthHelper, renderTemplate } from '@helpers';
+import developStorySkill from '../../templates/develop-story-skill.hbs';
+import { getNextTask } from './tools';
 
-const identificationNumberSchema = z.object({
-    identificationNumber: z.string().describe('The story identification number, e.g. "144154"'),
-});
-
-function createToolCallback<T extends Record<string, string>>(fn: (identificationNumber: string) => Promise<T>) {
-    return async ({ identificationNumber }: { identificationNumber: string }) => {
-        try {
-            const result = await fn(identificationNumber);
-            return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
-        } catch (error) {
-            return {
-                content: [{ type: 'text' as const, text: JSON.stringify({ error: error.message }) }],
-                isError: true,
-            };
-        }
-    };
+function installSkills(): void {
+    const skillDir = join(process.cwd(), '.claude', 'skills', 'develop-story');
+    if (!existsSync(join(process.cwd(), '.claude'))) return;
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, 'SKILL.md'), developStorySkill);
 }
 
 export async function startMcpServer(): Promise<void> {
+    installSkills();
+
     const initialized = await AuthHelper.initializeFromStoredCredentials();
     if (!initialized) {
         process.stderr.write('Error: Not authenticated. Please run "we-scrum login" first.\n');
@@ -35,44 +29,22 @@ export async function startMcpServer(): Promise<void> {
     server.registerTool(
         '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: identificationNumberSchema,
-        },
-        createToolCallback(getNextTask),
-    );
-
-    server.registerTool(
-        'start_task',
-        {
-            description: `Mark the next pending task of a story as in progress.
-Call this before making any changes to the codebase, as instructed by get_next_task.`,
-            inputSchema: identificationNumberSchema,
-        },
-        createToolCallback(startTask),
-    );
-
-    server.registerTool(
-        'get_unit_test_guidelines',
-        {
-            description: `Get unit test writing guidelines for the current pending task of a story.
-Call this tool when get_next_task returns unitTests instructions to run it.`,
-            inputSchema: identificationNumberSchema,
+            description: renderTemplate('get-next-task-description'),
+            inputSchema: z.object({
+                identificationNumber: z.string().describe('The story identification number, e.g. "144154"'),
+            }),
         },
-        createToolCallback(getUnitTestGuidelines),
-    );
-
-    server.registerTool(
-        'complete_task',
-        {
-            description: `Mark the current in-progress task of a story as done.
-Call this after committing all changes, as instructed by get_next_task.`,
-            inputSchema: identificationNumberSchema,
+        async ({ identificationNumber }) => {
+            try {
+                const markdown = await getNextTask(identificationNumber);
+                return { content: [{ type: 'text' as const, text: markdown }] };
+            } catch (error) {
+                return {
+                    content: [{ type: 'text' as const, text: JSON.stringify({ error: error.message }) }],
+                    isError: true,
+                };
+            }
         },
-        createToolCallback(completeTask),
     );
 
     const transport = new StdioServerTransport();