Add --mission CLI Flag To Display Mission Statement

by ADMIN 52 views

Introduction

In this article, we will explore the implementation of a new --mission CLI flag in src/lib/main.js that reads and prints the contents of the project-level MISSION.md. This feature will surface the library's mission directly to users, addressing the fact that no existing feature or command currently references the mission statement.

Why Implement a --mission CLI Flag?

The --mission CLI flag is essential for several reasons:

  • Transparency: By surfacing the mission statement, we provide users with a clear understanding of the library's purpose and values.
  • User Experience: The flag will enable users to quickly access the mission statement, making it easier for them to understand the library's context and goals.
  • Consistency: Implementing a consistent way to display the mission statement will help maintain a professional and cohesive user experience.

Scope & Changes

To implement the --mission CLI flag, we will make the following changes:

1. src/lib/main.js

Add Import Statements

We will add the following import statements to src/lib/main.js:

import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

These imports will allow us to read the contents of MISSION.md and locate it using fileURLToPath and import.meta.url.

Create a New Helper Function

We will create a new helper function async function processMission(args) that:

  • Checks for --mission in args.
  • Reads MISSION.md content.
  • Logs the raw mission markdown to the console.
  • Returns true when the flag is handled.

Here is the implementation of the processMission function:

async function processMission(args) {
    if (args.includes('--mission')) {
        const missionPath = fileURLToPath(new URL('./MISSION.md', import.meta.url));
        const missionContent = readFileSync(missionPath, 'utf8');
        console.log(missionContent);
        return true;
    }
    return false;
}

Update generateUsage()

We will update generateUsage() to include a --mission Show the project mission statement entry:

function generateUsage() {
    // ...
    usage.addOption(
        new Option({
            name: '--mission',
            description: 'Show the project mission statement',
        }),
    );
    // ...
}

Invoke processMission() in main()

We will invoke await processMission(args) in main() immediately after the help/version handlers:

async function main() {
    // ...
    if (await processMission(args)) {
        return;
    }
    // ...
}

2. tests/unit/main.test.js

Mock the fs Module

We will mock the fs module to return a dummy mission text:

vi.mock('fs', () => ({
    readFileSync: () => 'This is a dummy mission statement.',
}));

Spy on console.log

We will spy on console.log and verify:

  • Running main(['--mission']) prints the mocked mission text exactly once.
  • main() returns early after handling --mission (i.e., does not proceed to other flags).

Here is the implementation of the test:

it('should print the mission statement when --mission is passed', async () => {
    const consoleLogSpy = vi.spyOn(console, 'log');
    await main(['--mission']);
    expect(consoleLogSpy).toHaveBeenCalledTimes(1);
    expect(consoleLogSpy).toHaveBeenCalledWith('This is a dummy mission statement.');
});

it('should return early after handling --mission', async () => {
    const mainSpy = vi.spyOn(main, 'main');
    await main(['--mission']);
    expect(mainSpy).toHaveBeenCalledTimes(1);
});

3. sandbox/README.md

Add a New Section

We will add a new section under "Usage" describing the --mission flag and linking to MISSION.md in the repo root:

## Usage

*   `npm start -- --mission`: Show the project mission statement.

Provide an Example Invocation

We will provide an example invocation:

## Usage

*   `npm start -- --mission`: Show the project mission statement.

Verification & Acceptance

To verify and accept the changes, we will:

  • Run npm test to confirm all tests (including the new --mission tests) pass.
  • Manually execute npm start -- --mission and confirm the full contents of MISSION.md are output to stdout.

Conclusion

Q: What is the purpose of the --mission CLI flag?

A: The --mission CLI flag is designed to surface the library's mission statement directly to users. This feature addresses the fact that no existing feature or command currently references the mission statement, providing users with a clear understanding of the library's purpose and values.

Q: How does the --mission CLI flag work?

A: The --mission CLI flag works by reading the contents of the project-level MISSION.md file and printing it to the console. When the flag is passed, the processMission function is invoked, which checks for the flag in the command-line arguments, reads the mission statement, logs it to the console, and returns true to indicate that the flag has been handled.

Q: What changes were made to src/lib/main.js?

A: The following changes were made to src/lib/main.js:

  • Added import statements for readFileSync and fileURLToPath.
  • Created a new helper function processMission that checks for the --mission flag, reads the mission statement, logs it to the console, and returns true.
  • Updated generateUsage to include a --mission option.
  • Invoked await processMission(args) in main() immediately after the help/version handlers.

Q: What changes were made to tests/unit/main.test.js?

A: The following changes were made to tests/unit/main.test.js:

  • Mocked the fs module to return a dummy mission text.
  • Spied on console.log to verify that the mission statement is printed exactly once when the --mission flag is passed.
  • Verified that main() returns early after handling the --mission flag.

Q: What changes were made to sandbox/README.md?

A: The following changes were made to sandbox/README.md:

  • Added a new section under "Usage" describing the --mission flag and linking to MISSION.md in the repo root.
  • Provided an example invocation for the --mission flag.

Q: How do I verify and accept the changes?

A: To verify and accept the changes, run npm test to confirm all tests (including the new --mission tests) pass. Then, manually execute npm start -- --mission and confirm that the full contents of MISSION.md are output to stdout.

Q: Are there any new files or dependencies required?

A: No new files or dependencies are required. Only updates to src/lib/main.js, tests/unit/main.test.js, and sandbox/README.md are necessary.

Q: What are the benefits of implementing the --mission CLI flag?

A: The benefits of implementing the --mission CLI flag include:

  • Transparency: By surfacing the mission statement, users have a clear understanding of the library's purpose and values.
  • User Experience: The flag provides a consistent way to display the mission statement, making it easier for users to the library's context and goals.
  • Consistency: Implementing a consistent way to display the mission statement helps maintain a professional and cohesive user experience.