@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/cli/cli-commands/common/workspaceRepository.ts

@@ -0,0 +1,301 @@
+import { spawn } from 'child_process';
+import { lstat, realpath } from 'fs/promises';
+import { dirname, join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import { loadPromptsModule } from '../../common/loadPromptsModule';
+import type { NormalizedQuestionsCliOptions } from './questionsCliOptions';
+import { resolveProjectDirectory } from './projectCliOptions';
+
+/**
+ * Resolved project directory and its enclosing working tree. Project artifacts belong to `projectPath`;
+ * Git paths and synchronization belong to `repositoryRoot`, which may be an enclosing monorepo.
+ *
+ * @private shared workspace context for Coder and workspace server commands
+ */
+export type WorkspaceRepositoryContext = {
+    readonly projectPath: string;
+    readonly repositoryRoot?: string;
+    readonly gitDirectory?: string;
+    readonly repositoryStatus: 'missing' | 'reused' | 'initialized';
+};
+
+/**
+ * Command policy is separate from discovery: previews never initialize; explicit init needs no confirmation.
+ *
+ * @private shared workspace policy for Coder and workspace server commands
+ */
+export type WorkspaceRepositoryPolicy = 'initialize' | 'mutate' | 'read-only';
+
+/**
+ * Resolves the requested project once and discovers Git using Git itself, without requiring `HEAD`.
+ * Broken metadata, bare repositories, ownership errors and unavailable Git are failures, not missing repositories.
+ *
+ * @private shared workspace discovery for CLI commands
+ */
+export async function $resolveWorkspaceRepository(
+    projectDirectory = process.cwd(),
+): Promise<WorkspaceRepositoryContext> {
+    const projectPath = await resolveProjectDirectory(projectDirectory);
+    return $inspectWorkspaceRepository(projectPath);
+}
+
+/**
+ * Checks the shared prerequisite before any project writes, Git synchronization, installation or startup.
+ * Only an affirmative interactive answer or an explicit initializer authorizes `git init`.
+ *
+ * @private shared workspace preflight for Coder and workspace server commands
+ */
+export async function $preflightWorkspaceRepository(
+    options: {
+        readonly projectDirectory?: string;
+        readonly policy: WorkspaceRepositoryPolicy;
+    } & Partial<NormalizedQuestionsCliOptions>,
+): Promise<WorkspaceRepositoryContext> {
+    const workspace = await $resolveWorkspaceRepository(options.projectDirectory);
+    if (workspace.repositoryStatus !== 'missing') {
+        if (options.policy === 'initialize') {
+            console.info(
+                `Reusing Git repository \`${workspace.repositoryRoot}\` for project \`${workspace.projectPath}\`.`,
+            );
+        }
+        return workspace;
+    }
+
+    const recovery = spaceTrim(`
+        Run \`ptbk init\`, \`ptbk coder init\`, or \`git init\` in \`${workspace.projectPath}\`, then retry.
+    `);
+    const diagnostic = spaceTrim(`
+        No Git working tree contains project \`${workspace.projectPath}\`.
+
+        ${recovery}
+    `);
+    if (options.policy === 'read-only') {
+        console.warn(`Warning: ${diagnostic}`);
+        return workspace;
+    }
+    if (options.policy === 'mutate') {
+        if (
+            options.isAskingQuestionsEnabled === false ||
+            !process.stdin.isTTY ||
+            process.stdin.destroyed ||
+            process.stdin.readableEnded
+        ) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `${diagnostic}\n\nRepository initialization requires an interactive answer; \`--no-questions\` is not consent.`,
+                ),
+            );
+        }
+        console.info(`Target project directory: \`${workspace.projectPath}\`.`);
+        const { default: prompts } = await loadPromptsModule();
+        let answer: { readonly isInitializingRepository?: boolean };
+        try {
+            answer = await prompts({
+                type: 'confirm',
+                name: 'isInitializingRepository',
+                message: `Initialize a Git repository in ${workspace.projectPath}?`,
+                initial: false,
+            });
+        } catch (error) {
+            throw new NotAllowed(
+                spaceTrim(`
+                Git initialization confirmation failed. The command stopped before project setup.
+                ${recovery}
+
+                ${describeWorkspaceError(error)}
+            `),
+            );
+        }
+        if (answer.isInitializingRepository !== true) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `Git initialization was declined or cancelled. The command stopped before project setup.\n\n${recovery}`,
+                ),
+            );
+        }
+    }
+
+    // A parent repository may have appeared while the user answered. Recheck before creating metadata.
+    const recheckedWorkspace = await $inspectWorkspaceRepository(workspace.projectPath);
+    if (recheckedWorkspace.repositoryStatus !== 'missing') return recheckedWorkspace;
+    try {
+        await $runWorkspaceGit(workspace.projectPath, ['init']);
+        const initializedWorkspace = await $inspectWorkspaceRepository(workspace.projectPath);
+        if (!initializedWorkspace.repositoryRoot) {
+            throw new EnvironmentMismatchError('Git did not create a valid working tree.');
+        }
+        console.info(`Git repository initialized in \`${initializedWorkspace.repositoryRoot}\`.`);
+        return { ...initializedWorkspace, repositoryStatus: 'initialized' };
+    } catch (error) {
+        throw new EnvironmentMismatchError(
+            spaceTrim(`
+            Git initialization failed in \`${workspace.projectPath}\`.
+            Project scaffolding, harness installation and command execution have not started.
+            Git may have left partial metadata; inspect it and fix directory permissions before retrying.
+
+            ${describeWorkspaceError(error)}
+        `),
+        );
+    }
+}
+
+/** Discovers and validates a working tree at an already resolved project directory. */
+async function $inspectWorkspaceRepository(projectPath: string): Promise<WorkspaceRepositoryContext> {
+    let flags: string;
+    try {
+        flags = await $runWorkspaceGit(projectPath, ['rev-parse', '--is-bare-repository', '--is-inside-work-tree']);
+    } catch (error) {
+        const details = describeWorkspaceError(error);
+        if (/fatal: not a git repository \(or any (?:of the )?parent/iu.test(details)) {
+            // Git can ignore a damaged `.git` directory and report no repository. Such metadata must be repaired,
+            // never replaced by init. This check supplements Git discovery; it is not the repository detector.
+            await $assertNoBrokenRepositoryMetadata(projectPath);
+            return { projectPath, repositoryStatus: 'missing' };
+        }
+        throw workspaceDiscoveryError(projectPath, error);
+    }
+    const [isBareRepository, isInsideWorkingTree] = flags.trim().split(/\r?\n/u);
+    if (isBareRepository === 'true' || isInsideWorkingTree !== 'true') {
+        throw new EnvironmentMismatchError(
+            spaceTrim(`
+            Project \`${projectPath}\` is in a bare repository or outside its Git working tree.
+            Use a working-tree checkout of the project. No repository was initialized.
+        `),
+        );
+    }
+    try {
+        // Normalize Git's path spelling to match the resolved project (including Windows separators
+        // and filesystem aliases) before comparing ancestor directories.
+        const repositoryRoot = await realpath(
+            (await $runWorkspaceGit(projectPath, ['rev-parse', '--show-toplevel'])).trim(),
+        );
+        // Git may skip damaged inner metadata and find a valid parent. Do not silently use that parent
+        // for a project whose own checkout needs repair.
+        await $assertNoBrokenRepositoryMetadata(projectPath, repositoryRoot);
+        const gitDirectory = await realpath(
+            (await $runWorkspaceGit(projectPath, ['rev-parse', '--absolute-git-dir'])).trim(),
+        );
+        // Also validate the index and metadata, without refreshing the index or depending on an existing commit.
+        await $runWorkspaceGit(projectPath, ['status', '--porcelain', '--untracked-files=no']);
+        return { projectPath, repositoryRoot, gitDirectory, repositoryStatus: 'reused' };
+    } catch (error) {
+        throw workspaceDiscoveryError(projectPath, error);
+    }
+}
+
+/** Checks ancestors only to disambiguate genuinely absent metadata from broken or inaccessible metadata. */
+async function $assertNoBrokenRepositoryMetadata(projectPath: string, repositoryRoot?: string): Promise<void> {
+    let directory = projectPath;
+    while (directory !== repositoryRoot) {
+        const metadataPath = join(directory, '.git');
+        try {
+            await lstat(metadataPath);
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw workspaceDiscoveryError(projectPath, error);
+            const parentDirectory = dirname(directory);
+            if (parentDirectory === directory) return;
+            directory = parentDirectory;
+            continue;
+        }
+        throw new EnvironmentMismatchError(
+            spaceTrim(`
+            Git could not read repository metadata at \`${metadataPath}\` for project \`${projectPath}\`.
+            Repair the invalid or inaccessible metadata before retrying. No repository was initialized.
+        `),
+        );
+    }
+}
+
+/**
+ * Executes Git without a shell, optional index locks, or credential prompts, retaining raw output boundaries.
+ * Drains both output streams without execFile's fixed buffer limit so large repository listings remain complete.
+ * @private shared Git discovery and commit-scope inspection
+ */
+export async function $runWorkspaceGit(
+    projectPath: string,
+    argumentsList: ReadonlyArray<string>,
+    options?: {
+        readonly env?: Record<string, string>;
+        readonly signal?: AbortSignal;
+        readonly input?: string | Buffer;
+    },
+): Promise<string> {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', [...argumentsList], {
+            cwd: projectPath,
+            env: { ...process.env, LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', ...options?.env },
+            windowsHide: true,
+            signal: options?.signal,
+        });
+        const stdoutChunks: string[] = [];
+        const stderrChunks: string[] = [];
+        let processError: Error | undefined;
+        let inputError: Error | undefined;
+        // Stream decoding preserves multibyte filenames even when a character spans two output chunks.
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk: string) => stdoutChunks.push(chunk));
+        child.stderr.on('data', (chunk: string) => stderrChunks.push(chunk));
+        child.on('error', (error) => {
+            processError = error;
+        });
+        child.stdin.on('error', (error) => {
+            // A failed Git command may close stdin early. Keep its exit status and stderr as the primary error.
+            inputError = error;
+        });
+        child.on('close', (code, signal) => {
+            const stdout = stdoutChunks.join('');
+            const stderr = stderrChunks.join('');
+            if (processError) {
+                reject(Object.assign(processError, { stdout, stderr }));
+            } else if (code !== 0 || signal) {
+                reject(
+                    Object.assign(new Error(`Command failed: git ${argumentsList.join(' ')}\n${stderr}`), {
+                        code,
+                        signal,
+                        killed: child.killed,
+                        stdout,
+                        stderr,
+                    }),
+                );
+            } else if (inputError) {
+                reject(Object.assign(inputError, { stdout, stderr }));
+            } else {
+                resolve(stdout);
+            }
+        });
+        // Index-info uses NUL-delimited input. Closing stdin also lets commands finish when input is empty.
+        child.stdin.end(options?.input);
+    });
+}
+
+/** Translates discovery failures without ever treating an ownership or executable error as permission to init. */
+function workspaceDiscoveryError(projectPath: string, error: unknown): EnvironmentMismatchError {
+    const details = describeWorkspaceError(error);
+    const isGitUnavailable = (error as NodeJS.ErrnoException)?.code === 'ENOENT';
+    const hint = isGitUnavailable
+        ? 'Git is not available on `PATH`. Install Git or fix `PATH`, then retry.'
+        : /dubious ownership|safe.directory/iu.test(details)
+        ? 'Git rejected repository ownership. Review the ownership and trust of this specific checkout before retrying.'
+        : 'Check repository metadata, permissions and Git configuration before retrying.';
+    return new EnvironmentMismatchError(
+        spaceTrim(`
+        Cannot inspect Git for project \`${projectPath}\`.
+        ${hint}
+        No repository was initialized and project setup has not started.
+
+        ${details}
+    `),
+    );
+}
+
+/** Extracts useful Git stderr or filesystem diagnostics from a process failure. */
+function describeWorkspaceError(error: unknown): string {
+    const failure = error as { stderr?: string; message?: string };
+    return failure?.stderr?.trim() || failure?.message || String(error);
+}
+
+// Note: [🟡] Code for workspace Git preflight [workspaceRepository](src/cli/cli-commands/common/workspaceRepository.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

package/src/cli/cli-commands/common/workspaceRepositoryCliOptions.ts

@@ -0,0 +1,31 @@
+import type { Command } from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { addQuestionsOption } from './questionsCliOptions';
+import { addProjectPathOption } from './projectCliOptions';
+
+/**
+ * Shared explanation of the workspace prerequisite, independent of commit and synchronization settings.
+ * @private internal CLI help text
+ */
+export const WORKSPACE_REPOSITORY_DESCRIPTION = spaceTrim(`
+    Workspace Git prerequisite:
+    - Workspace actions inspect the enclosing Git working tree, including worktrees and submodules
+    - ptbk init and ptbk coder init automatically initialize Git if it is missing; existing repositories are reused
+    - Other mutating actions ask once before initializing Git in the displayed project directory
+    - --no-questions and noninteractive input require an existing repository; recover with ptbk init, ptbk coder init, or git init
+    - Read-only inspection and --dry-run only warn when Git is missing and never initialize it
+    - --no-commit disables commits, not repository detection; a local repository needs no remote
+`);
+
+/**
+ * Adds shared Git help and the questions switch to every workspace command without duplicating existing options.
+ * @private internal registration helper for workspace CLI commands
+ */
+export function addWorkspaceRepositoryOptions(command: Command): void {
+    addProjectPathOption(command);
+    if (!command.options.some((option) => option.long === '--no-questions')) addQuestionsOption(command);
+    command.addHelpText('after', `\n${WORKSPACE_REPOSITORY_DESCRIPTION}\n`);
+}
+
+// Note: [🟡] Code for workspace CLI options [workspaceRepositoryCliOptions](src/cli/cli-commands/common/workspaceRepositoryCliOptions.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

package/src/cli/cli-commands/prettify.ts

@@ -3,12 +3,12 @@ import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { readFile, writeFile } from 'fs/promises';
-import glob from 'glob-promise'; // <- TODO: [🚰] Use just 'glob'
 import { basename } from 'path';
 import { spaceTrim } from 'spacetrim';
 import { prettifyPipelineString } from '../../conversion/prettify/prettifyPipelineString';
 import { assertsError } from '../../errors/assertsError';
 import { validatePipelineString } from '../../pipeline/validatePipelineString';
+import { findFilesByGlob } from '../../utils/files/findFilesByGlob';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 import { handleActionErrors } from './common/handleActionErrors';
 
@@ -40,7 +40,7 @@ export function $initializePrettifyCommand(program: Program): $side_effect {
     prettifyCommand.action(
         handleActionErrors(async (filesGlob, cliOptions) => {
             const { ignore, verbose: isVerbose } = cliOptions;
-            const filenames = await glob(filesGlob!, { ignore });
+            const filenames = await findFilesByGlob(filesGlob!, { ignore });
             //                       <- TODO: [😶]
 
             for (const filename of filenames) {

package/src/cli/cli-commands/run.ts

@@ -13,7 +13,9 @@ import type { RunCommandCliOptions } from './run/runCommandAction';
  * @private internal function of `promptbookCli`
  */
 export function $initializeRunCommand(program: Program): $side_effect {
-    const runCommand = program.command('run', { isDefault: true });
+    // Note: `run` is deprecated, so it is intentionally NOT the default command of `ptbk`
+    //       and it must be asked for explicitly
+    const runCommand = program.command('run');
 
     configureRunCommand(runCommand);
     runCommand.action(

package/src/cli/cli-commands/test-command.ts

@@ -3,7 +3,6 @@ import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { readFile } from 'fs/promises';
-import glob from 'glob-promise'; // <- TODO: [🚰] Use just 'glob'
 import { basename } from 'path';
 import { spaceTrim } from 'spacetrim';
 import { getAllCommitmentsToolFunctionsForNode } from '../../commitments/_common/getAllCommitmentsToolFunctionsForNode';
@@ -18,6 +17,7 @@ import { validatePipelineString } from '../../pipeline/validatePipelineString';
 import { $provideFilesystemForNode } from '../../scrapers/_common/register/$provideFilesystemForNode';
 import { $provideScrapersForNode } from '../../scrapers/_common/register/$provideScrapersForNode';
 import { JavascriptExecutionTools } from '../../scripting/javascript/JavascriptExecutionTools';
+import { findFilesByGlob } from '../../utils/files/findFilesByGlob';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 import { $provideLlmToolsForCli } from '../common/$provideLlmToolsForCli';
 import { handleActionErrors } from './common/handleActionErrors';
@@ -89,7 +89,7 @@ export function $initializeTestCommand(program: Program): $side_effect {
 
             const ignore = (ignoreRaw as string).split(',').map((pattern) => pattern.trim());
 
-            const filenames = await glob(filesGlob!, { ignore });
+            const filenames = await findFilesByGlob(filesGlob!, { ignore });
             //                       <- TODO: [😶]
 
             // console.log({ filesGlob, ignore, filenames });

package/src/cli/common/$deprecateCliCommand.ts

@@ -2,10 +2,14 @@ import colors from 'colors';
 import { Command } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $hideCliCommandFromHelp } from './$hideCliCommandFromHelp';
 
 /**
  * Marks one CLI command as deprecated while keeping it available for existing callers.
  *
+ * Deprecated commands are not advertised anymore - they are hidden from the list of commands in the help of their
+ * parent command, they warn when they are used and they explain the deprecation in their own help.
+ *
  * @private utility of CLI
  */
 export function $deprecateCliCommand(command: Command, deprecationMessage: string): $side_effect {
@@ -21,6 +25,7 @@ export function $deprecateCliCommand(command: Command, deprecationMessage: strin
     command.hook('preAction', () => {
         console.warn(colors.yellow(createDeprecatedCliCommandWarning(command, deprecationMessage)));
     });
+    $hideCliCommandFromHelp(command);
 }
 
 /**

package/src/cli/common/$hideCliCommandFromHelp.ts

@@ -0,0 +1,27 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+
+/**
+ * Shape of the Commander internals which decide whether one command is listed among the subcommands in the help
+ *
+ * Note: Commander accepts hiding only while the command is being registered - `program.command(name, { hidden: true })`
+ *       or `program.addCommand(command, { hidden: true })` - and exposes no setter for an already registered command,
+ *       so the very same flag which both of them set is written here directly.
+ *
+ * @private internal type of `$hideCliCommandFromHelp`
+ */
+type CommandWithHiddenFlag = {
+    _hidden: boolean;
+};
+
+/**
+ * Keeps one already registered CLI command out of the help of its parent command while the command itself stays
+ * fully usable - it can still be run, it still has its own help and it is still reachable through `ptbk help <command>`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it changes how the CLI renders its help
+ *
+ * @private utility of CLI
+ */
+export function $hideCliCommandFromHelp(command: Command): $side_effect {
+    (command as unknown as CommandWithHiddenFlag)._hidden = true;
+}

package/src/cli/common/$requireCliSubcommand.ts

@@ -0,0 +1,35 @@
+import colors from 'colors';
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+
+/**
+ * Message printed when one CLI command which only groups subcommands is run without picking any of them.
+ *
+ * @private internal constant of `$requireCliSubcommand`
+ */
+const MISSING_CLI_SUBCOMMAND_MESSAGE = 'Please specify a subcommand.';
+
+/**
+ * Makes one CLI command which only groups subcommands ask for a subcommand instead of doing anything on its own.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers an action in the CLI
+ *
+ * @private utility of CLI
+ */
+export function $requireCliSubcommand(command: Command): $side_effect {
+    command.action(() => $reportMissingCliSubcommand(command));
+}
+
+/**
+ * Asks for a subcommand of one CLI command, prints its help and exits the process.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it writes to the console and exits the process
+ *
+ * @private utility of CLI
+ */
+export function $reportMissingCliSubcommand(command: Command): never {
+    console.info(colors.yellow(MISSING_CLI_SUBCOMMAND_MESSAGE));
+    console.info('');
+
+    return command.help();
+}

package/src/cli/promptbookCli.ts

@@ -1,52 +1,11 @@
 import colors from 'colors';
 import commander from 'commander';
 import { spaceTrim } from 'spacetrim';
-import { CLAIM } from '../config';
 import { EnvironmentMismatchError } from '../errors/EnvironmentMismatchError';
 import { $isRunningInNode } from '../utils/environment/$isRunningInNode';
 import { PROMPTBOOK_ENGINE_VERSION } from '../version';
-import { $initializeAboutCommand } from './cli-commands/about';
-import { $initializeAgentCommand } from './cli-commands/agent';
-import { $initializeAgentFolderCommand } from './cli-commands/agent-folder';
-import { $initializeAgentsServerCommand } from './cli-commands/agents-server';
-import { $initializeCoderCommand } from './cli-commands/coder';
-import { $initializeHelloCommand } from './cli-commands/hello';
-import { $initializeListModelsCommand } from './cli-commands/list-models';
-import { $initializeListScrapersCommand } from './cli-commands/list-scrapers';
-import { $initializeLoginCommand } from './cli-commands/login';
-import { $initializeMakeCommand } from './cli-commands/make';
-import { $initializePrettifyCommand } from './cli-commands/prettify';
-import { $initializeRunCommand } from './cli-commands/run';
-import { $initializeStartAgentsServerCommand } from './cli-commands/start-agents-server';
-import { $initializeStartPipelinesServerCommand } from './cli-commands/start-pipelines-server';
-import { $initializeTestCommand } from './cli-commands/test-command';
-import { $addGlobalOptionsToCommand } from './common/$addGlobalOptionsToCommand';
-import { $deprecateCliCommand } from './common/$deprecateCliCommand';
-
-/**
- * Shared deprecation text for top-level CLI commands backed by the old pipeline system.
- */
-const OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE = 'This command is part of the old pipeline system.';
-
-/**
- * Shared deprecation text for top-level CLI commands backed by the old pre-agent system.
- */
-const OLD_SYSTEM_DEPRECATION_MESSAGE = 'This command is part of the old system.';
-
-/**
- * Deprecation guidance for top-level `ptbk` commands that remain for compatibility.
- */
-const DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES: Readonly<Record<string, string>> = {
-    run: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
-    login: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
-    make: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
-    prettify: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
-    test: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
-    'list-models': OLD_SYSTEM_DEPRECATION_MESSAGE,
-    'list-scrapers': OLD_SYSTEM_DEPRECATION_MESSAGE,
-    'start-agents-server': 'Use `ptbk agents-server start` instead.',
-    'start-pipelines-server': OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
-};
+import { $initializePromptbookCliProgram } from './$initializePromptbookCliProgram';
+import { $reportMissingCliSubcommand } from './common/$requireCliSubcommand';
 
 /**
  * Raw top-level CLI arguments that print the Promptbook version.
@@ -89,38 +48,12 @@ export async function promptbookCli(): Promise<void> {
     }
 
     const program = new commander.Command();
-    program.name('promptbook');
-    program.alias('ptbk');
-
-    program.version(PROMPTBOOK_ENGINE_VERSION);
-    program.description(CLAIM);
-
-    // Note: These options are valid for all commands
-
-    $initializeAboutCommand(program);
-    $initializeRunCommand(program);
-    $initializeLoginCommand(program);
-    $initializeHelloCommand(program);
-    $initializeMakeCommand(program);
-    $initializePrettifyCommand(program);
-    $initializeTestCommand(program);
-    $initializeListModelsCommand(program);
-    $initializeListScrapersCommand(program);
-    $initializeStartAgentsServerCommand(program);
-    $initializeStartPipelinesServerCommand(program);
-    $initializeAgentCommand(program);
-    $initializeAgentFolderCommand(program);
-    $initializeAgentsServerCommand(program);
-    $initializeCoderCommand(program);
-
-    $deprecateTopLevelCommands(program);
-
-    // TODO: [🧠] Should it be here or not> $addGlobalOptionsToCommand(program);
-    program.commands.forEach($addGlobalOptionsToCommand);
+    $initializePromptbookCliProgram(program);
 
+    // Note: There is no default command, so `ptbk` without a subcommand asks for one
+    //       instead of running the deprecated `ptbk run`
     if (commandLineArguments.length === 0) {
-        program.outputHelp();
-        return process.exit(0);
+        return $reportMissingCliSubcommand(program);
     }
 
     program.parse(process.argv);
@@ -137,21 +70,7 @@ function isTopLevelVersionRequested(commandLineArguments: ReadonlyArray<string>)
     return firstCommandLineArgument !== undefined && VERSION_OPTION_ARGUMENTS.has(firstCommandLineArgument);
 }
 
-/**
- * Adds one deprecation notice to each configured top-level legacy command.
- */
-function $deprecateTopLevelCommands(program: commander.Command): void {
-    for (const command of program.commands) {
-        const deprecationMessage = DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES[command.name()];
-
-        if (deprecationMessage !== undefined) {
-            $deprecateCliCommand(command, deprecationMessage);
-        }
-    }
-}
-
 // Note: [🟡] Code for CLI program [promptbookCli](src/cli/promptbookCli.ts) should never be published outside of `@promptbook/cli`
-// TODO: [🧠] Maybe `run` command the default, instead of `ptbk run ./foo.book` -> `ptbk ./foo.book`
 // TODO: [🥠] Do not export, its just for CLI script
 // TODO: [🕌] When more functionalities, rename
 // Note: 11:11

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.ts

@@ -214,20 +214,64 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
 
     /**
      * Retrieves the permanent ID of an agent by its name or permanent ID.
+     *
+     * An agent that still exists always wins over a soft-deleted one, so a name that was deleted and
+     * later created again resolves to the agent that is live now instead of to the recycle-bin leftover.
+     * Soft-deleted agents stay resolvable as a fallback because the recycle bin restores them by name
+     * or permanent id.
      */
     public async getAgentPermanentId(
         agentNameOrPermanentId: string_agent_name | string_agent_permanent_id,
     ): Promise<string_agent_permanent_id> {
-        const selectResult = await this.supabaseClient
+        const activeAgentPermanentId = await this.findAgentPermanentId(agentNameOrPermanentId, {
+            isDeletedAgentIncluded: false,
+        });
+
+        if (activeAgentPermanentId !== null) {
+            return activeAgentPermanentId;
+        }
+
+        const deletedAgentPermanentId = await this.findAgentPermanentId(agentNameOrPermanentId, {
+            isDeletedAgentIncluded: true,
+        });
+
+        if (deletedAgentPermanentId !== null) {
+            return deletedAgentPermanentId;
+        }
+
+        throw new NotFoundError(`Agent with name or id "${agentNameOrPermanentId}" not found`);
+    }
+
+    /**
+     * Looks up the permanent id of the oldest agent matching one name or permanent id.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+     * @param options - Whether soft-deleted agents may be matched as well.
+     * @returns Permanent id of the matched agent, or `null` when nothing matches.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private async findAgentPermanentId(
+        agentNameOrPermanentId: string_agent_name | string_agent_permanent_id,
+        options: { readonly isDeletedAgentIncluded: boolean },
+    ): Promise<string_agent_permanent_id | null> {
+        const selectQuery = this.supabaseClient
             .from(this.getTableName('Agent'))
             .select('permanentId')
-            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId))
+            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId));
+
+        if (!options.isDeletedAgentIncluded) {
+            selectQuery.is('deletedAt', null);
+        }
+
+        const selectResult = await selectQuery
             .order('createdAt', { ascending: true }) // Pick oldest if multiple match by name
             .limit(1);
 
         if (selectResult.error || !selectResult.data || selectResult.data.length === 0) {
-            throw new NotFoundError(`Agent with name or id "${agentNameOrPermanentId}" not found`);
+            return null;
         }
+
         return selectResult.data[0]!.permanentId as string_agent_permanent_id;
     }