@promptbook/cli 0.114.0-3 → 0.114.0-30

package/src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.ts

@@ -0,0 +1,259 @@
+import { readFile } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import {
+    PROMPTBOOK_CLI_NPM_PACKAGE_NAMES,
+    type LocalPromptbookCliInstallation,
+    type PromptbookCliInstallation,
+    type PromptbookCliInstallationLocation,
+    type PromptbookCliNpmPackageName,
+} from './PromptbookCliInstallation';
+
+/**
+ * Time limit for listing directly installed global npm packages.
+ */
+const NPM_GLOBAL_PACKAGE_LIST_COMMAND_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * Filename of an npm package manifest.
+ */
+const PACKAGE_JSON_FILENAME = 'package.json';
+
+/**
+ * Directory containing locally installed npm packages.
+ */
+const NODE_MODULES_DIRECTORY_NAME = 'node_modules';
+
+/**
+ * JSON object shape used while reading package manifests without assuming unrelated fields.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+type JsonObject = Readonly<Record<string, unknown>>;
+
+/**
+ * Finds every directly declared local or directly installed global Promptbook CLI package which can be updated.
+ *
+ * Transitive packages are deliberately ignored because this command must update the dependency chosen by the current
+ * project or global npm installation, not mutate a dependency owned by another package.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests and runs npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>> {
+    const [localInstallations, globalInstallations] = await Promise.all([
+        $resolveLocalPromptbookCliInstallations(),
+        $resolveGlobalPromptbookCliInstallations(),
+    ]);
+
+    return [...localInstallations, ...globalInstallations];
+}
+
+/**
+ * Finds the closest ancestor `package.json` which directly declares a Promptbook CLI package.
+ */
+async function $resolveLocalPromptbookCliInstallations(): Promise<ReadonlyArray<LocalPromptbookCliInstallation>> {
+    let candidateProjectPath = resolve(process.cwd());
+    let isFileSystemRootReached = false;
+
+    while (!isFileSystemRootReached) {
+        const projectPackageJson = await $readJsonObject(join(candidateProjectPath, PACKAGE_JSON_FILENAME));
+
+        if (projectPackageJson !== null) {
+            const declaredPackages = resolveDeclaredPromptbookCliPackages(projectPackageJson);
+
+            if (declaredPackages.length > 0) {
+                const installations = await Promise.all(
+                    declaredPackages.map(async ({ npmPackageName, installationLocation }) => {
+                        const installedVersion = await $resolveLocalInstalledNpmPackageVersion(
+                            candidateProjectPath,
+                            npmPackageName,
+                        );
+
+                        return installedVersion === null
+                            ? undefined
+                            : {
+                                  npmPackageName,
+                                  installedVersion,
+                                  installationLocation,
+                                  projectPath: candidateProjectPath,
+                              };
+                    }),
+                );
+
+                return installations.filter(isDefined);
+            }
+        }
+
+        const parentPath = dirname(candidateProjectPath);
+        isFileSystemRootReached = parentPath === candidateProjectPath;
+        candidateProjectPath = parentPath;
+    }
+
+    return [];
+}
+
+/**
+ * Finds Promptbook CLI package names declared in dependencies or development dependencies.
+ */
+function resolveDeclaredPromptbookCliPackages(packageJson: JsonObject): ReadonlyArray<{
+    readonly npmPackageName: PromptbookCliNpmPackageName;
+    readonly installationLocation: Exclude<PromptbookCliInstallationLocation, 'global'>;
+}> {
+    const declaredPackages: Array<{
+        readonly npmPackageName: PromptbookCliNpmPackageName;
+        readonly installationLocation: Exclude<PromptbookCliInstallationLocation, 'global'>;
+    }> = [];
+
+    for (const npmPackageName of PROMPTBOOK_CLI_NPM_PACKAGE_NAMES) {
+        if (readNestedStringProperty(packageJson, 'dependencies', npmPackageName) !== undefined) {
+            declaredPackages.push({ npmPackageName, installationLocation: 'local-dependency' });
+            continue;
+        }
+
+        if (readNestedStringProperty(packageJson, 'devDependencies', npmPackageName) !== undefined) {
+            declaredPackages.push({ npmPackageName, installationLocation: 'local-development-dependency' });
+        }
+    }
+
+    return declaredPackages;
+}
+
+/**
+ * Reads an installed local package version while following npm's ancestor `node_modules` lookup behavior.
+ */
+async function $resolveLocalInstalledNpmPackageVersion(
+    projectPath: string,
+    npmPackageName: PromptbookCliNpmPackageName,
+): Promise<string | null> {
+    let candidateNodeModulesParentPath = projectPath;
+    let isFileSystemRootReached = false;
+
+    while (!isFileSystemRootReached) {
+        const installedPackageJson = await $readJsonObject(
+            join(candidateNodeModulesParentPath, NODE_MODULES_DIRECTORY_NAME, npmPackageName, PACKAGE_JSON_FILENAME),
+        );
+        const installedVersion =
+            installedPackageJson === null ? undefined : readStringProperty(installedPackageJson, 'version');
+
+        if (installedVersion !== undefined) {
+            return installedVersion;
+        }
+
+        const parentPath = dirname(candidateNodeModulesParentPath);
+        isFileSystemRootReached = parentPath === candidateNodeModulesParentPath;
+        candidateNodeModulesParentPath = parentPath;
+    }
+
+    return null;
+}
+
+/**
+ * Finds Promptbook CLI packages listed by npm as direct global installations.
+ */
+async function $resolveGlobalPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>> {
+    const output = await $execCommand({
+        command: 'npm list --global --depth=0 --json --loglevel=error',
+        // Note: npm can return a non-zero status for an unrelated broken global package while still printing useful JSON
+        crashOnError: false,
+        timeout: NPM_GLOBAL_PACKAGE_LIST_COMMAND_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+    const globalPackageList = parseJsonObjectFromCommandOutput(output);
+    const globalDependencies =
+        globalPackageList === null ? null : readObjectProperty(globalPackageList, 'dependencies');
+
+    if (globalDependencies === null) {
+        return [];
+    }
+
+    return PROMPTBOOK_CLI_NPM_PACKAGE_NAMES.flatMap((npmPackageName) => {
+        const packageMetadata = readObjectProperty(globalDependencies, npmPackageName);
+        const installedVersion = packageMetadata === null ? undefined : readStringProperty(packageMetadata, 'version');
+
+        return installedVersion === undefined
+            ? []
+            : [{ npmPackageName, installedVersion, installationLocation: 'global' as const }];
+    });
+}
+
+/**
+ * Reads a JSON object, returning `null` for missing or malformed files because update checks must stay advisory.
+ */
+async function $readJsonObject(filePath: string): Promise<JsonObject | null> {
+    try {
+        const parsedValue: unknown = JSON.parse(await readFile(filePath, 'utf8'));
+
+        return isJsonObject(parsedValue) ? parsedValue : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Parses a JSON object from command output while tolerating npm warnings around the JSON payload.
+ */
+function parseJsonObjectFromCommandOutput(output: string): JsonObject | null {
+    const jsonStartIndex = output.indexOf('{');
+    const jsonEndIndex = output.lastIndexOf('}');
+
+    if (jsonStartIndex === -1 || jsonEndIndex < jsonStartIndex) {
+        return null;
+    }
+
+    try {
+        const parsedValue: unknown = JSON.parse(output.slice(jsonStartIndex, jsonEndIndex + 1));
+
+        return isJsonObject(parsedValue) ? parsedValue : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Checks whether an unknown value can be read as a JSON object.
+ */
+function isJsonObject(value: unknown): value is JsonObject {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reads one string property from a JSON object.
+ */
+function readStringProperty(jsonObject: JsonObject, propertyName: string): string | undefined {
+    const value = jsonObject[propertyName];
+
+    return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * Reads one object property from a JSON object.
+ */
+function readObjectProperty(jsonObject: JsonObject, propertyName: string): JsonObject | null {
+    const value = jsonObject[propertyName];
+
+    return isJsonObject(value) ? value : null;
+}
+
+/**
+ * Reads one string property nested under another JSON object property.
+ */
+function readNestedStringProperty(
+    jsonObject: JsonObject,
+    parentPropertyName: string,
+    propertyName: string,
+): string | undefined {
+    const nestedValue = readObjectProperty(jsonObject, parentPropertyName);
+
+    return nestedValue === null ? undefined : readStringProperty(nestedValue, propertyName);
+}
+
+/**
+ * Narrows an array after `undefined` values were removed.
+ */
+function isDefined<TValue>(value: TValue | undefined): value is TValue {
+    return value !== undefined;
+}
+
+// Note: [🟡] Code for Promptbook CLI installation detection [$resolvePromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.ts

@@ -0,0 +1,55 @@
+import colors from 'colors';
+import { spaceTrim } from 'spacetrim';
+import { assertsError } from '../../../../errors/assertsError';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import { buildPromptbookCliInstallCommand } from './buildPromptbookCliInstallCommand';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+
+/**
+ * Updates one Promptbook CLI package in its existing local or global location.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs an npm package
+ *
+ * @returns `true` when the package update succeeds, `false` when it fails
+ * @private internal utility of `promptbookCli`
+ */
+export async function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean> {
+    const { npmPackageName, installationLocation } = status.installation;
+    const installCommand = buildPromptbookCliInstallCommand(status.installation);
+    const updateWorkingDirectory = installationLocation === 'global' ? process.cwd() : status.installation.projectPath;
+
+    console.info(colors.cyan(`Updating Promptbook CLI package \`${npmPackageName}\` with \`${installCommand}\`...`));
+
+    try {
+        await $execCommand({
+            command: installCommand,
+            cwd: updateWorkingDirectory,
+            crashOnError: true,
+            isVerbose: true,
+        });
+    } catch (error) {
+        assertsError(error);
+        const updateErrorMessage = error.message;
+
+        console.error(
+            colors.red(
+                spaceTrim(
+                    (block) => `
+                        Could not update **Promptbook CLI** package \`${npmPackageName}\`.
+
+                        Update it manually with \`${installCommand}\` and run the command again.
+
+                        ${block(updateErrorMessage)}
+                    `,
+                ),
+            ),
+        );
+
+        return false;
+    }
+
+    console.info(colors.green(`Promptbook CLI package \`${npmPackageName}\` has been updated.`));
+    return true;
+}
+
+// Note: [🟡] Code for Promptbook CLI installation update [$updatePromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts

@@ -0,0 +1,76 @@
+import type { NpmPackageInstallationLocation } from '../npm/buildNpmPackageInstallCommand';
+
+/**
+ * Npm packages which directly provide the `ptbk` executable.
+ *
+ * `ptbk` is the preferred package and forwards to `@promptbook/cli`; the latter can also be installed directly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const PROMPTBOOK_CLI_NPM_PACKAGE_NAMES = ['ptbk', '@promptbook/cli'] as const;
+
+/**
+ * Npm package which directly provides the `ptbk` executable.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliNpmPackageName = (typeof PROMPTBOOK_CLI_NPM_PACKAGE_NAMES)[number];
+
+/**
+ * Place where one Promptbook CLI package is installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationLocation = NpmPackageInstallationLocation;
+
+/**
+ * Fields shared by local and global Promptbook CLI installations.
+ *
+ * @private internal utility of `PromptbookCliInstallation`
+ */
+type PromptbookCliInstallationBase = {
+    /**
+     * Npm package that provides the CLI.
+     */
+    readonly npmPackageName: PromptbookCliNpmPackageName;
+
+    /**
+     * Version from the installed package's `package.json`.
+     */
+    readonly installedVersion: string;
+};
+
+/**
+ * One directly declared local Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type LocalPromptbookCliInstallation = PromptbookCliInstallationBase & {
+    /**
+     * Local manifest section containing the package.
+     */
+    readonly installationLocation: Exclude<PromptbookCliInstallationLocation, 'global'>;
+
+    /**
+     * Project directory containing the `package.json` which declares the package.
+     */
+    readonly projectPath: string;
+};
+
+/**
+ * One directly installed global Promptbook CLI package.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type GlobalPromptbookCliInstallation = PromptbookCliInstallationBase & {
+    readonly installationLocation: 'global';
+};
+
+/**
+ * One local or global Promptbook CLI package that can be updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallation = LocalPromptbookCliInstallation | GlobalPromptbookCliInstallation;
+
+// Note: [🟡] Code for Promptbook CLI installation definitions [PromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallationStatus.ts

@@ -0,0 +1,32 @@
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+
+/**
+ * Result of comparing one installed Promptbook CLI package with the newest published version.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationState = 'up-to-date' | 'outdated' | 'unknown';
+
+/**
+ * Version status of one Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationStatus = {
+    /**
+     * Installed CLI package being checked.
+     */
+    readonly installation: PromptbookCliInstallation;
+
+    /**
+     * Result of comparing the installed version with the newest published version.
+     */
+    readonly installationState: PromptbookCliInstallationState;
+
+    /**
+     * Newest published package version, or `null` when npm could not be reached.
+     */
+    readonly latestVersion: string | null;
+};
+
+// Note: [🟡] Code for Promptbook CLI installation status [PromptbookCliInstallationStatus](src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallationStatus.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.ts

@@ -0,0 +1,13 @@
+import { buildNpmPackageInstallCommand } from '../npm/buildNpmPackageInstallCommand';
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+
+/**
+ * Builds the npm command that updates one existing Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function buildPromptbookCliInstallCommand(installation: PromptbookCliInstallation): string {
+    return buildNpmPackageInstallCommand(installation.npmPackageName, installation.installationLocation);
+}
+
+// Note: [🟡] Code for Promptbook CLI installation command [buildPromptbookCliInstallCommand](src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.ts

@@ -0,0 +1,45 @@
+import { spaceTrim } from 'spacetrim';
+import type { PromptbookCliInstallationLocation } from './PromptbookCliInstallation';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+
+/**
+ * Formats the warning shown when one or more Promptbook CLI installations are outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatPromptbookCliInstallationWarning(
+    statuses: ReadonlyArray<PromptbookCliInstallationStatus>,
+): string {
+    const statusLines = statuses.map((status) => {
+        const { npmPackageName, installedVersion, installationLocation } = status.installation;
+
+        return `- ${formatPromptbookCliInstallationLocation(
+            installationLocation,
+        )} \`${npmPackageName}\`: installed \`${installedVersion}\`, newest \`${status.latestVersion}\``;
+    });
+
+    return spaceTrim(
+        (block) => `
+            **Promptbook CLI** is outdated.
+
+            ${block(statusLines.join('\n'))}
+        `,
+    );
+}
+
+/**
+ * Describes an installation location in text suitable for an update warning.
+ */
+function formatPromptbookCliInstallationLocation(installationLocation: PromptbookCliInstallationLocation): string {
+    if (installationLocation === 'global') {
+        return 'Globally installed';
+    }
+
+    if (installationLocation === 'local-development-dependency') {
+        return 'Locally in `devDependencies`';
+    }
+
+    return 'Locally in `dependencies`';
+}
+
+// Note: [🟡] Code for Promptbook CLI installation warning [formatPromptbookCliInstallationWarning](src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.ts) should never be published outside of `@promptbook/cli`

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;
     }
 

package/src/commands/FORMAT/formatCommandParser.ts

@@ -70,8 +70,10 @@ export const formatCommandParser: PipelineTaskCommandParser<FormatCommand> = {
      */
     $applyToTaskJson(command: FormatCommand, $taskJson: $TaskJson): $side_effect {
         if ($taskJson.format !== undefined && command.format !== $taskJson.format) {
-            throw new ParseError(`Format format is already defined to "${$taskJson.format}".
-                Now you try to redefine it by "${command.format}"`);
+            throw new ParseError(
+                spaceTrim(`Format format is already defined to "${$taskJson.format}".
+                Now you try to redefine it by "${command.format}"`),
+            );
         }
         $taskJson.format = command.format;
     },

package/src/commitments/ACTION/ACTION.ts

@@ -66,7 +66,7 @@ export class ActionCommitmentDefinition extends BaseCommitmentDefinition<'ACTION
             Research Assistant
 
             PERSONA You are a helpful research assistant
-            USE SEARCH ENGINE
+            USE MCP https://mcp.example.com/server
             RULE Always cite your sources when providing information from the web
             \`\`\`
 
@@ -86,8 +86,8 @@ export class ActionCommitmentDefinition extends BaseCommitmentDefinition<'ACTION
             Code Assistant
 
             PERSONA You are a programming assistant
-            USE BROWSER
-            USE SEARCH ENGINE
+            USE PROJECT https://github.com/example/project
+            USE MCP https://mcp.example.com/server
             RULE Prefer the narrowest useful capability for the task.
             \`\`\`
         `);

package/src/commitments/FROM/FROM.ts

@@ -46,6 +46,12 @@ export class FromCommitmentDefinition extends BaseCommitmentDefinition<'FROM'> {
 
             Inherits agent source from another agent.
 
+            Every agent inherits from the core agent \`@Adam\` unless it says otherwise, so writing no ${this.type} at all
+            is the same as writing \`${this.type} @Adam\`. Write \`${this.type} @Null\` to inherit from nothing.
+
+            An agent has exactly one parent, so when ${this.type} is written more than once, the last one wins and
+            overrides every earlier one.
+
             ## Examples
 
             \`\`\`book
@@ -54,6 +60,13 @@ export class FromCommitmentDefinition extends BaseCommitmentDefinition<'FROM'> {
             FROM https://s6.ptbk.io/benjamin-white
             RULE Speak only in English.
             \`\`\`
+
+            \`\`\`book
+            My Standalone Agent
+
+            FROM @Null
+            RULE Speak only in English.
+            \`\`\`
         `);
     }
 

package/src/commitments/{META → META_DESCRIPTION}/META_DESCRIPTION.ts

@@ -20,7 +20,7 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  */
 export class MetaDescriptionCommitmentDefinition extends BaseCommitmentDefinition<'META DESCRIPTION'> {
     public constructor() {
-        super('META DESCRIPTION', ['DESCRIPTION']);
+        super('META DESCRIPTION');
     }
 
     /**