@promptbook/cli 0.114.0-42 → 0.114.0-48

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

@@ -0,0 +1,265 @@
+import { execFile } from 'child_process';
+import { lstat, realpath, stat } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { promisify } from 'util';
+import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import { loadPromptsModule } from '../../common/loadPromptsModule';
+import type { NormalizedQuestionsCliOptions } from './questionsCliOptions';
+
+/** Shell-free Git execution, also usable from the packaged CLI. */
+const EXECUTE_FILE = promisify(execFile);
+
+/**
+ * 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 requestedPath = resolve(projectDirectory);
+    let projectPath: string;
+    try {
+        projectPath = await realpath(requestedPath);
+        if (!(await stat(projectPath)).isDirectory()) {
+            throw new EnvironmentMismatchError(`The project path \`${requestedPath}\` is not a directory.`);
+        }
+    } catch (error) {
+        throw new EnvironmentMismatchError(
+            spaceTrim(
+                `Cannot access project directory \`${requestedPath}\`. Check that it exists and is accessible.\n\n${describeWorkspaceError(
+                    error,
+                )}`,
+            ),
+        );
+    }
+    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 $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. */
+async function $runWorkspaceGit(projectPath: string, argumentsList: ReadonlyArray<string>): Promise<string> {
+    const result = await EXECUTE_FILE('git', [...argumentsList], {
+        cwd: projectPath,
+        env: { ...process.env, LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' },
+        windowsHide: true,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return result.stdout;
+}
+
+/** 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,29 @@
+import type { Command } from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { addQuestionsOption } from './questionsCliOptions';
+
+/**
+ * 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 {
+    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/commitments/TEAM/TEAM.ts

@@ -171,6 +171,18 @@ export class TeamCommitmentDefinition extends BaseCommitmentDefinition<'TEAM'> {
 
             Registers teammate agents that the current agent can consult via tools.
 
+            The primary agent sends a question and relevant context to a teammate and receives an attributed answer.
+            Each teammate uses its own Book. Declaring a team makes advisers available when relevant; it does not
+            merge their rules into the primary agent or start every teammate automatically.
+
+            In \`ptbk coder run\` and \`ptbk coder plan\`, TEAM entries in the selected Book, its ancestors and imports
+            use the existing reference rules: \`@Name\`, \`{Agent Name}\`, \`{./lawyer.book}\`, project paths such as
+            \`{agents/lawyer.book}\`, and HTTP(S) Book URLs. Local advisers require no Agents Server. A remote Book
+            must be readable through its normal endpoint; private or inaccessible sources return errors.
+            Coding harnesses expose scoped command tools; planning uses restricted host tools and currently requires
+            OpenAI Codex. Planning restrictions apply to every adviser, including custom Developer Books.
+            The primary agent retains responsibility for the task, PRD proposals and final output.
+
             ## Examples
 
             \`\`\`book
@@ -216,22 +228,32 @@ export class TeamCommitmentDefinition extends BaseCommitmentDefinition<'TEAM'> {
         >;
 
         const resolvedTeammates: TeamTeammate[] = resolveTeamTeammateLabels(trimmedContent, teammates);
+        const toolUrls = new Map(existingTeammates.map((teammate) => [teammate.toolName, teammate.url]));
 
         const teamEntries: TeamToolEntry[] = resolvedTeammates.map((teammate) => {
             const profile = preResolvedProfiles[teammate.url];
             const resolvedLabel = profile?.agentName || teammate.label;
             const existingTeammate = existingTeammates.find((entry) => entry.url === teammate.url);
+            const baseToolName = existingTeammate?.toolName || createTeamToolName(teammate.url, resolvedLabel);
+            let toolName = baseToolName;
+            let suffix = 1;
+            // Explicit paths can identify distinct Books with the same display name or normalized label.
+            while (toolUrls.has(toolName) && toolUrls.get(toolName) !== teammate.url) {
+                toolName = `${baseToolName}_${++suffix}`;
+            }
+            toolUrls.set(toolName, teammate.url);
             return {
-                toolName: (existingTeammate?.toolName ||
-                    createTeamToolName(teammate.url, resolvedLabel)) as string_javascript_name,
+                toolName: toolName as string_javascript_name,
                 teammate: { ...teammate, label: resolvedLabel },
                 agentName,
                 description: profile?.personaDescription || null,
             };
         });
 
-        for (const entry of teamEntries) {
-            registerTeamTool(entry);
+        if (!requirements._metadata?.isTeamToolRegistrationDisabled) {
+            for (const entry of teamEntries) {
+                registerTeamTool(entry);
+            }
         }
 
         const existingTools: readonly LlmToolDefinition[] = requirements.tools || [];

package/src/conversion/archive/loadJsZipModule.ts

@@ -7,4 +7,6 @@ import { createLazyModuleLoader } from '../../utils/misc/createLazyModuleLoader'
  *
  * @private internal utility of `loadArchive` and `saveArchive`
  */
-export const loadJsZipModule = createLazyModuleLoader(() => import('jszip'));
+export const loadJsZipModule: () => Promise<{ default: typeof import('jszip') }> = createLazyModuleLoader(
+    () => import('jszip'),
+);