@promptbook/cli 0.113.0-9 → 0.114.0-1

package/src/cli/cli-commands/coder/add.ts

@@ -0,0 +1,330 @@
+import colors from 'colors';
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import prompts from 'prompts';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import { ParseError } from '../../../errors/ParseError';
+import { normalizeToKebabCase } from '../../../utils/normalization/normalize-to-kebab-case';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { handleActionErrors } from '../common/handleActionErrors';
+import {
+    buildCoderPromptSection,
+    getDefaultCoderPromptTemplateDefinitions,
+    PROMPTS_DIRECTORY_PATH,
+    resolveCoderPromptTemplate,
+} from './boilerplateTemplates';
+
+/**
+ * Placeholder token replaced when a prompt is authored — see the `@@@` convention.
+ *
+ * @private internal utility of `coder add` command
+ */
+const PROMPT_TEMPLATE_PLACEHOLDER = '@@@';
+
+/**
+ * Maximum number of kebab-case words kept from the description when building the prompt filename slug.
+ *
+ * @private internal utility of `coder add` command
+ */
+const MAX_PROMPT_SLUG_WORD_COUNT = 8;
+
+/**
+ * Fallback filename slug used when the description has no alphanumeric characters.
+ *
+ * @private internal utility of `coder add` command
+ */
+const FALLBACK_PROMPT_SLUG = 'prompt';
+
+/**
+ * Initializes `coder add` command for Promptbook CLI utilities
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeCoderAddCommand(program: Program): $side_effect {
+    const command = program.command('add');
+    command.description(
+        spaceTrim(`
+            Add one ready-to-run prompt file to the queue
+
+            Provide the description as an argument, pipe it through stdin, or run without arguments to type it interactively:
+            - \`ptbk coder add "some new feature"\`
+            - \`ptbk coder add --priority 1 "some new feature"\`
+            - \`ptbk coder add <<EOF ... EOF\`
+            - \`ptbk coder add\`
+        `),
+    );
+
+    command.argument('[description]', 'Plain-language description of the feature or task to implement');
+    command.option(
+        '--priority <priority>',
+        'Priority of the new prompt — higher priorities run first (rendered as trailing `!` markers)',
+        parsePriorityOption,
+        0,
+    );
+    command.option(
+        '--template <template>',
+        spaceTrim(`
+            Prompt template appended below the description.
+
+            Accepts either a built-in alias (${getDefaultCoderPromptTemplateDefinitions()
+                .map(({ id }) => id)
+                .join(', ')}) or a markdown file path relative to the current project root.
+        `),
+    );
+
+    command.action(
+        handleActionErrors(async (descriptionArgument: string | undefined, cliOptions) => {
+            const { priority, template: templateOption } = cliOptions as {
+                readonly priority: number;
+                readonly template?: string;
+            };
+
+            const description = await resolveCoderPromptDescription(descriptionArgument);
+
+            await addCoderPrompt({
+                projectPath: process.cwd(),
+                description,
+                priority,
+                templateOption,
+            });
+        }),
+    );
+}
+
+/**
+ * Result of adding one prompt file with `coder add`.
+ *
+ * @private internal utility of `coder add` command
+ */
+export type AddCoderPromptResult = {
+    /**
+     * Project-relative path of the created prompt file.
+     */
+    readonly filePath: string;
+    /**
+     * Emoji tag assigned to the created prompt, for example `[✨🪴]`.
+     */
+    readonly emojiTag: string;
+};
+
+/**
+ * Adds one ready-to-run prompt file containing a single prompt built from the description and template.
+ *
+ * @private internal utility of `coder add` command
+ */
+export async function addCoderPrompt({
+    projectPath,
+    description,
+    priority,
+    templateOption,
+}: {
+    readonly projectPath: string;
+    readonly description: string;
+    readonly priority: number;
+    readonly templateOption?: string;
+}): Promise<AddCoderPromptResult> {
+    const normalizedDescription = description.trim();
+    if (normalizedDescription === '') {
+        throw new ParseError(
+            spaceTrim(`
+                Cannot add a prompt without a description.
+
+                Provide the description as an argument, pipe it through stdin, or type it interactively:
+                - \`ptbk coder add "some new feature"\`
+            `),
+        );
+    }
+
+    // Note: Import these dynamically to avoid circular dependencies and keep the CLI fast
+    const { buildPromptFilename, getPromptNumbering } = await import(
+        '../../../../scripts/utils/prompts/getPromptNumbering'
+    );
+    const { formatPromptEmojiTag, getFreshPromptEmojiTags } = await import(
+        '../../../../scripts/utils/prompts/promptEmojiTags'
+    );
+
+    const promptsDirectory = join(projectPath, PROMPTS_DIRECTORY_PATH);
+    mkdirSync(promptsDirectory, { recursive: true });
+
+    const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
+
+    const promptNumbering = await getPromptNumbering({
+        promptsDir: promptsDirectory,
+        step: 10,
+        ignoreGlobs: ['**/node_modules/**'],
+    });
+
+    const { selectedEmojis } = await getFreshPromptEmojiTags({ count: 1, rootDir: projectPath });
+    const emoji = selectedEmojis[0]!;
+    const emojiTag = formatPromptEmojiTag(emoji);
+
+    const [firstDescriptionLine, ...remainingDescriptionLines] = normalizedDescription.split('\n');
+    const title = (firstDescriptionLine ?? '').trim();
+    const descriptionDetail = remainingDescriptionLines.join('\n').trim();
+    const templateRules = stripPromptTemplatePlaceholder(promptTemplate.content);
+    const body = descriptionDetail === '' ? templateRules : `${descriptionDetail}\n\n${templateRules}`;
+
+    const section = buildCoderPromptSection({
+        statusLine: buildPromptStatusLine(priority),
+        emojiTag,
+        title,
+        body,
+    });
+
+    const slug = buildAddPromptSlug(promptTemplate.slugPrefix, title);
+    const filename = buildPromptFilename(promptNumbering.datePrefix, promptNumbering.startNumber, slug);
+    const filePath = join(PROMPTS_DIRECTORY_PATH, filename);
+    const absoluteFilePath = join(projectPath, filePath);
+
+    writeFileSync(absoluteFilePath, `${section}\n`, 'utf-8');
+
+    console.info(colors.green(`✓ Added prompt ${emojiTag} in ${filePath}`));
+
+    return { filePath, emojiTag };
+}
+
+/**
+ * Resolves the prompt description from the CLI argument, piped stdin, or an interactive prompt.
+ *
+ * @private internal utility of `coder add` command
+ */
+async function resolveCoderPromptDescription(descriptionArgument: string | undefined): Promise<string> {
+    if (descriptionArgument !== undefined && descriptionArgument.trim() !== '') {
+        return descriptionArgument.trim();
+    }
+
+    // Note: A non-TTY stdin means the description is piped in (e.g. a `<<EOF` heredoc or `echo ... |`)
+    const isStandardInputPiped = !process.stdin.isTTY;
+    if (isStandardInputPiped) {
+        const standardInputDescription = (await readAllStandardInput()).trim();
+        if (standardInputDescription === '') {
+            throw new ParseError(
+                spaceTrim(`
+                    Cannot add a prompt without a description.
+
+                    The piped standard input was empty — provide the description as an argument instead:
+                    - \`ptbk coder add "some new feature"\`
+                `),
+            );
+        }
+        return standardInputDescription;
+    }
+
+    const response = await prompts({
+        type: 'text',
+        name: 'description',
+        message: 'Describe the feature or task to add',
+        validate: (value) => (typeof value === 'string' && value.trim() !== '' ? true : 'Description is required'),
+    });
+
+    const interactiveDescription = typeof response.description === 'string' ? response.description.trim() : '';
+    if (interactiveDescription === '') {
+        throw new ParseError(
+            spaceTrim(`
+                Cannot add a prompt without a description.
+
+                Provide the description as an argument, pipe it through stdin, or type it interactively:
+                - \`ptbk coder add "some new feature"\`
+            `),
+        );
+    }
+
+    return interactiveDescription;
+}
+
+/**
+ * Reads the whole standard input stream into a single UTF-8 string.
+ *
+ * @private internal utility of `coder add` command
+ */
+async function readAllStandardInput(): Promise<string> {
+    const chunks: Array<Buffer> = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+
+/**
+ * Builds the checklist status line for a ready-to-run prompt at the given priority.
+ *
+ * A priority of `0` produces a plain `[ ]`, while a priority of `N` appends `N` trailing `!` markers.
+ *
+ * @private internal utility of `coder add` command
+ */
+function buildPromptStatusLine(priority: number): string {
+    if (priority <= 0) {
+        return '[ ]';
+    }
+    return `[ ] ${'!'.repeat(priority)}`;
+}
+
+/**
+ * Removes the `@@@` placeholder lines from a resolved template so only the task rules remain.
+ *
+ * @private internal utility of `coder add` command
+ */
+function stripPromptTemplatePlaceholder(templateContent: string): string {
+    return templateContent
+        .split('\n')
+        .filter((line) => !isPromptTemplatePlaceholderLine(line))
+        .join('\n')
+        .trim();
+}
+
+/**
+ * Checks whether one line is only the `@@@` placeholder, optionally prefixed by a list marker.
+ *
+ * @private internal utility of `coder add` command
+ */
+function isPromptTemplatePlaceholderLine(line: string): boolean {
+    const lineWithoutListMarker = line
+        .trim()
+        .replace(/^[-*+]\s+/u, '')
+        .trim();
+    return lineWithoutListMarker === PROMPT_TEMPLATE_PLACEHOLDER;
+}
+
+/**
+ * Builds the filename slug from the optional template prefix and the prompt title.
+ *
+ * @private internal utility of `coder add` command
+ */
+function buildAddPromptSlug(templateSlugPrefix: string | null, title: string): string {
+    const titleSlug =
+        normalizeToKebabCase(title).split('-').filter(Boolean).slice(0, MAX_PROMPT_SLUG_WORD_COUNT).join('-') ||
+        FALLBACK_PROMPT_SLUG;
+
+    if (!templateSlugPrefix) {
+        return titleSlug;
+    }
+    return `${templateSlugPrefix}-${titleSlug}`;
+}
+
+/**
+ * Parses and validates the `--priority` option as a non-negative integer.
+ *
+ * @private internal utility of `coder add` command
+ */
+function parsePriorityOption(value: string): number {
+    const parsedValue = Number(value);
+    if (!Number.isInteger(parsedValue) || parsedValue < 0) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`--priority\`: \`${value}\`.
+
+                Use a non-negative integer, for example \`--priority 1\`.
+            `),
+        );
+    }
+    return parsedValue;
+}
+
+// Note: [🟡] Code for CLI command [add](src/cli/cli-commands/coder/add.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/coder/agentCodingFile.ts

@@ -1,6 +1,12 @@
 import { spaceTrim } from 'spacetrim';
 import { AGENTS_FILE_PATH } from './agentsFile';
-import { getDefaultCoderProjectPromptTemplateDefinitions, getDefaultCoderPromptTemplateDefinitions, PROMPTS_DIRECTORY_PATH, PROMPTS_DONE_DIRECTORY_PATH, PROMPTS_TEMPLATES_DIRECTORY_PATH } from './boilerplateTemplates';
+import {
+    getDefaultCoderProjectPromptTemplateDefinitions,
+    getDefaultCoderPromptTemplateDefinitions,
+    PROMPTS_DIRECTORY_PATH,
+    PROMPTS_DONE_DIRECTORY_PATH,
+    PROMPTS_TEMPLATES_DIRECTORY_PATH,
+} from './boilerplateTemplates';
 import { formatDisplayPath } from './formatDisplayPath';
 
 /**
@@ -33,7 +39,7 @@ export function getDefaultCoderAgentCodingFileContent({
             2. Create or customize prompt templates in \`${formatDisplayPath(
                 PROMPTS_TEMPLATES_DIRECTORY_PATH,
             )}/\`. ${buildStarterTemplateSentence()}
-            3. Generate prompt files with \`npm run coder:generate-boilerplates\` or \`ptbk coder generate-boilerplates --template <template> --count <count>\`.
+            3. Generate prompt files with \`npm run coder:generate-boilerplates\` or \`ptbk coder generate-boilerplates --template <template> --count <count>\`. To append a single ready-to-run prompt straight from a description, use \`npm run coder:add\` or \`ptbk coder add "some new feature"\`.
             4. Replace every \`@@@\`, keep drafts as \`[-]\`, and switch prompts to \`[ ]\` when they are ready to run. Completed prompts are marked \`[x]\`.
             5. Run \`npm run coder:run\` to execute the next ready prompt with the configured coding agent.
             6. Use \`npm run coder:verify\` to archive finished prompts into \`${formatDisplayPath(
@@ -65,7 +71,7 @@ export function getDefaultCoderAgentCodingFileContent({
 
             ## Customizing the workflow
             -   Edit \`package.json\` if you want \`npm run coder:run\` to use another coding agent, model, thinking level, context file, or wait mode.
-            -   Use direct CLI commands when you need one-off flags such as \`--priority\`, \`--ignore-git-changes\`, \`--no-commit\`, \`--dry-run\`, \`--test\`, \`--allow-credits\`, or \`--auto-migrate\`.
+            -   Use direct CLI commands when you need one-off flags such as \`--min-priority\`, \`--max-priority\`, \`--ignore-git-changes\`, \`--no-commit\`, \`--dry-run\`, \`--test\`, \`--allow-credits\`, or \`--auto-migrate\`.
             -   Use \`ptbk coder --help\` and \`ptbk coder <command> --help\` for the full CLI reference.
         `,
     );
@@ -108,6 +114,12 @@ function describeDefaultCoderPackageJsonScript(scriptName: string, scriptCommand
         )}/\`.`;
     }
 
+    if (scriptName === 'coder:add') {
+        return `Runs \`${scriptCommand}\` to add one ready-to-run prompt file to \`${formatDisplayPath(
+            PROMPTS_DIRECTORY_PATH,
+        )}/\` from a plain-language description.`;
+    }
+
     if (scriptName === 'coder:run') {
         return `Runs \`${scriptCommand}\` to execute the next ready prompt with shared repository context from \`${AGENTS_FILE_PATH}\`.`;
     }

package/src/cli/cli-commands/coder/boilerplateTemplates.ts

@@ -268,6 +268,46 @@ export async function resolveCoderPromptTemplate({
     }
 }
 
+/**
+ * Builds one prompt section (status line, emoji-tagged title, and body) shared by
+ * `coder generate-boilerplates` and `coder add`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export function buildCoderPromptSection({
+    statusLine,
+    emojiTag,
+    title,
+    body,
+}: {
+    /**
+     * Checklist status marker of the section, for example `[-]`, `[ ]`, or `[ ] !!`.
+     */
+    readonly statusLine: string;
+    /**
+     * Emoji tag rendered before the title, for example `[✨🪴]`.
+     */
+    readonly emojiTag: string;
+    /**
+     * Single-line title rendered right after the emoji tag.
+     */
+    readonly title: string;
+    /**
+     * Markdown body rendered below the title.
+     */
+    readonly body: string;
+}): string {
+    return spaceTrim(
+        (block) => `
+            ${statusLine}
+
+            ${emojiTag} ${title}
+
+            ${block(body)}
+        `,
+    );
+}
+
 /**
  * Normalizes one raw `--template` option to either a trimmed string or `undefined`.
  */

package/src/cli/cli-commands/coder/generate-boilerplates.ts

@@ -1,13 +1,18 @@
 import colors from 'colors';
 import type {
-  Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
-import { getDefaultCoderPromptTemplateDefinitions, PROMPTS_DIRECTORY_PATH, resolveCoderPromptTemplate } from './boilerplateTemplates';
+import {
+    buildCoderPromptSection,
+    getDefaultCoderPromptTemplateDefinitions,
+    PROMPTS_DIRECTORY_PATH,
+    resolveCoderPromptTemplate,
+} from './boilerplateTemplates';
 
 /**
  * Initializes `coder generate-boilerplates` command for Promptbook CLI utilities
@@ -121,16 +126,12 @@ export async function generatePromptBoilerplate({
         const filepath = join(PROMPTS_DIRECTORY_PATH, filename);
         const absoluteFilepath = join(projectPath, filepath);
         const emojiTag = formatPromptEmojiTag(emoji);
-        const one = spaceTrim(
-            (block) => `
-
-                [-]
-
-                ${emojiTag} ${title}
-
-                ${block(promptTemplate.content)}
-            `,
-        );
+        const one = buildCoderPromptSection({
+            statusLine: '[-]',
+            emojiTag,
+            title,
+            body: promptTemplate.content,
+        });
         const content = spaceTrim(
             (block) => `
 

package/src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts

@@ -3,9 +3,10 @@
  */
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
+    'coder:add': 'ptbk coder add --template ./prompts/templates/common.md',
     'coder:run':
         'ptbk coder run --harness openai-codex --model gpt-5.5 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
-    // 'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
+    // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;
 

package/src/cli/cli-commands/coder/init.ts

@@ -4,6 +4,9 @@ import type {
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
+import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
+import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import { getDefaultCoderProjectPromptTemplateDefinitions } from './boilerplateTemplates';
@@ -17,6 +20,14 @@ export { getDefaultCoderPackageJsonScripts } from './getDefaultCoderPackageJsonS
 export { getDefaultCoderVscodeSettings } from './getDefaultCoderVscodeSettings';
 export { initializeCoderProjectConfiguration } from './initializeCoderProjectConfiguration';
 
+/**
+ * Harnesses whose global installation is checked by `ptbk coder init` so that the initialized
+ * project is ready to run coding prompts right away.
+ *
+ * @private internal constant of `coder init` command
+ */
+const CODER_INIT_CHECKED_HARNESS_NAMES: ReadonlyArray<PromptRunnerHarnessName> = ['openai-codex', 'claude-code'];
+
 /**
  * Initializes `coder init` command for Promptbook CLI utilities.
  *
@@ -28,25 +39,30 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
     const command = program.command('init');
     command.alias('initialize');
     command.description(
-        spaceTrim(`
-            Initialize Promptbook coder configuration for current project
+        spaceTrim(
+            (block) => `
+                Initialize Promptbook coder configuration for current project
+
+                Creates or updates:
+                - prompts/
+                - prompts/done/
+                ${block(listDefaultCoderProjectPromptTemplateDisplayPaths())}
+                - ${CODER_DEVELOPER_AGENT_FILE_PATH}
+                - ${AGENTS_FILE_PATH}
+                - ${AGENT_CODING_FILE_PATH}
+                - .gitignore
+                - package.json
+                - .vscode/settings.json
 
-            Creates or updates:
-            - prompts/
-            - prompts/done/
-            ${listDefaultCoderProjectPromptTemplateDisplayPaths()}
-            - ${CODER_DEVELOPER_AGENT_FILE_PATH}
-            - ${AGENTS_FILE_PATH}
-            - ${AGENT_CODING_FILE_PATH}
-            - .gitignore
-            - package.json
-            - .vscode/settings.json
+                Ensures required coding-agent environment variables in .env:
+                - CODING_AGENT_GIT_NAME
+                - CODING_AGENT_GIT_EMAIL
+                - CODING_AGENT_GIT_SIGNING_KEY
 
-            Ensures required coding-agent environment variables in .env:
-            - CODING_AGENT_GIT_NAME
-            - CODING_AGENT_GIT_EMAIL
-            - CODING_AGENT_GIT_SIGNING_KEY
-        `),
+                Checks that the coding harnesses are installed globally and up to date:
+                ${block(listCheckedHarnessLabels())}
+            `,
+        ),
     );
 
     command.action(
@@ -55,10 +71,20 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
             await generatePromptBoilerplate({ projectPath, filesCount: 5 });
+            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
         }),
     );
 }
 
+/**
+ * Lists the harnesses whose global installation is checked by `ptbk coder init`.
+ */
+function listCheckedHarnessLabels(): string {
+    return CODER_INIT_CHECKED_HARNESS_NAMES.map((harnessName) => `- ${getHarnessDefinition(harnessName).label}`).join(
+        '\n',
+    );
+}
+
 /**
  * Lists the project-owned template file paths created by `ptbk coder init`.
  */

package/src/cli/cli-commands/coder/initializeCoderProjectConfiguration.ts

@@ -1,7 +1,12 @@
 import { AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent } from './agentCodingFile';
 import { AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent } from './agentsFile';
 import type { EnsuredCoderPromptTemplateFile, InitializationStatus } from './boilerplateTemplates';
-import { ensureDefaultCoderPromptTemplateFiles, PROMPTS_DIRECTORY_PATH, PROMPTS_DONE_DIRECTORY_PATH, PROMPTS_TEMPLATES_DIRECTORY_PATH } from './boilerplateTemplates';
+import {
+    ensureDefaultCoderPromptTemplateFiles,
+    PROMPTS_DIRECTORY_PATH,
+    PROMPTS_DONE_DIRECTORY_PATH,
+    PROMPTS_TEMPLATES_DIRECTORY_PATH,
+} from './boilerplateTemplates';
 import { CODER_AGENTS_DIRECTORY_PATH, ensureCoderDeveloperAgentFile } from './ensureCoderDeveloperAgentFile';
 import { ensureCoderEnvFile } from './ensureCoderEnvFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';