@powerhousedao/ph-clint-cli 0.1.0-dev.8 → 0.1.0-dev.80

package/dist/codegen/exec.js

@@ -1,34 +1,7 @@
 /**
  * Small helpers for invoking external commands during code generation.
- *
- * We deliberately keep this separate from `ph-clint`'s process manager:
- * here we need synchronous-feeling prompt-forwarding (stdio inherited) so
- * the user can respond to interactive prompts from `ph init` or from a
- * package manager.
  */
 import { spawn } from 'node:child_process';
-/**
- * Run `command args` in `cwd`, forwarding stdio by default. Resolves to
- * the exit code. Does NOT throw on non-zero — callers decide how to react.
- */
-export async function runCommand(command, args, options) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(command, args, {
-            cwd: options.cwd,
-            stdio: options.stdio ?? 'inherit',
-            env: options.env ? { ...process.env, ...options.env } : process.env,
-        });
-        child.once('error', reject);
-        child.once('close', (code) => {
-            resolve({
-                command,
-                args,
-                cwd: options.cwd,
-                exitCode: code ?? 0,
-            });
-        });
-    });
-}
 /** Returns true if `command` is on PATH. */
 export async function hasCommandOnPath(command) {
     return new Promise((resolve) => {

package/dist/codegen/generated.d.ts

@@ -0,0 +1,17 @@
+import { type ClintProjectSpec } from '../spec/types.js';
+export interface GeneratedState {
+    name: string;
+    scope: string | undefined;
+    cliFolderName: string;
+    appFolderName: string;
+    /** True once `ph init` has run successfully in the app dir. */
+    appInitialized: boolean;
+}
+export declare function getGeneratedPath(targetDir: string): string;
+export declare function readGeneratedState(targetDir: string): Promise<GeneratedState | null>;
+export declare function writeGeneratedState(targetDir: string, state: GeneratedState): Promise<void>;
+/**
+ * Derive a `GeneratedState` from a spec. The `appInitialized` flag must be
+ * supplied by the caller (it depends on filesystem state, not the spec).
+ */
+export declare function generatedStateFromSpec(spec: ClintProjectSpec, appInitialized: boolean): GeneratedState;

package/dist/codegen/generated.js

@@ -0,0 +1,49 @@
+/**
+ * Tracks the derived state from the last successful code generation.
+ *
+ * Stored at `{targetDir}/.ph/ph-clint-cli/generated.json`. Used to detect
+ * folder renames (name/scope changes) and re-apply patches that depend on
+ * the project identity.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getAppFolderName, getCliFolderName, } from '../spec/types.js';
+const GEN_DIR = path.join('.ph', 'ph-clint-cli');
+const GEN_FILE = 'generated.json';
+export function getGeneratedPath(targetDir) {
+    return path.join(targetDir, GEN_DIR, GEN_FILE);
+}
+export async function readGeneratedState(targetDir) {
+    try {
+        const raw = await fs.readFile(getGeneratedPath(targetDir), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err &&
+            typeof err === 'object' &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function writeGeneratedState(targetDir, state) {
+    const file = getGeneratedPath(targetDir);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+/**
+ * Derive a `GeneratedState` from a spec. The `appInitialized` flag must be
+ * supplied by the caller (it depends on filesystem state, not the spec).
+ */
+export function generatedStateFromSpec(spec, appInitialized) {
+    const split = spec.features.powerhouse !== 'Disabled';
+    return {
+        name: spec.name,
+        scope: spec.scope,
+        cliFolderName: split ? getCliFolderName(spec) : '',
+        appFolderName: split ? getAppFolderName(spec) : '',
+        appInitialized,
+    };
+}

package/dist/codegen/index.d.ts

@@ -1,39 +1,11 @@
-import { type ClintProjectSpec } from '../spec/types.js';
-export type GenerateMode = 'create' | 'update' | 'auto';
-export interface GenerateProjectOptions {
-    /** Absolute path to the project root. */
-    targetDir: string;
-    spec: ClintProjectSpec;
-    /** Defaults to `'auto'` — create if no persisted spec, else update. */
-    mode?: GenerateMode;
-    /** Create mode: allow writing into a non-empty directory. */
-    allowNonEmpty?: boolean;
-    /**
-     * Update mode: overwrite user-edited files (hash-mismatch) anyway.
-     * Also relaxes the git-dirty guard on flat → split migration.
-     */
-    force?: boolean;
-    /** Optional warning sink (diagnostics, not errors). */
-    onWarn?: (msg: string) => void;
-}
-export interface GeneratedFile {
-    absolutePath: string;
-    relativePath: string;
-}
-export interface GenerateProjectResult {
-    mode: 'create' | 'update';
-    /** Files newly written or rewritten. */
-    files: GeneratedFile[];
-    /** Files skipped because the user had edited them. */
-    skipped: GeneratedFile[];
-    /** Files removed because the new spec no longer emits them. */
-    deleted: GeneratedFile[];
-    /** True if a flat → split migration ran. */
-    migrated: boolean;
-    cliDir: string;
-    appDir: string | null;
-}
 /**
- * Generate / reconcile a project at `targetDir` from the given spec.
+ * Re-exports from @powerhousedao/ph-clint-dev/codegen with CLI_VERSION default.
  */
+import { type GenerateProjectOptions as DevGenerateProjectOptions, type GenerateProjectResult, type GenerateMode, type GeneratedFile } from '@powerhousedao/ph-clint-dev/codegen';
+import type { CodegenContext } from '@powerhousedao/ph-clint-dev/codegen/types';
+export type { GenerateProjectResult, GenerateMode, GeneratedFile, CodegenContext };
+export interface GenerateProjectOptions extends Omit<DevGenerateProjectOptions, 'context'> {
+    /** Codegen context; defaults to CLI_VERSION when omitted. */
+    context?: CodegenContext;
+}
 export declare function generateProject(options: GenerateProjectOptions): Promise<GenerateProjectResult>;

package/dist/codegen/index.js

@@ -1,298 +1,11 @@
 /**
- * Code generator entry point.
- *
- * Takes a `ClintProjectSpec` + target directory and reconciles the on-disk
- * project tree with it.
- *
- * Two modes:
- *
- * - **create** — the target dir is empty (or only contains ignorable
- *   artefacts). Every templated file is written fresh. Refuses to
- *   overwrite existing non-empty state unless `allowNonEmpty`.
- *
- * - **update** — a previous run's spec exists at
- *   `.ph/ph-clint-cli/project-spec.json`. Re-runs the builders, then for
- *   each emitted file:
- *     - files containing `@clint:begin/@clint:end` markers (today: just
- *       `src/cli.ts`) have their marker regions spliced in-place, leaving
- *       user code outside markers untouched;
- *     - files without markers are overwritten iff their on-disk hash still
- *       matches the hash stored from the previous write (user-edited files
- *       are skipped and surfaced via `onWarn`);
- *     - files the new spec no longer emits are removed if their hash still
- *       matches.
- *
- * A spec flip of `features.powerhouse.enabled` from `false` to `true`
- * triggers the flat → split migration before the update flow runs.
- *
- * Mode is auto-detected by the presence of the persisted spec.
- */
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { getAppFolderName, getCliFolderName, } from '../spec/types.js';
-import { getSpecPath, readProjectSpec, writeProjectSpec, } from '../spec/file.js';
-import { hashContent, hashFile, readHashes, writeHashes, } from './hashes.js';
-import { hasMarkers, spliceMarkerRegions } from './markers.js';
-import { writeFileEnsuringDir, isDirEmptyEnough } from './write.js';
-import { migrateFlatToSplit } from './migrate/flat-to-split.js';
-import { CLI_FILE_BUILDERS, buildReadme, buildRootPackageJson, buildPublishConfigTs, buildAppIndexTs, } from './builders/index.js';
-/**
- * Generate / reconcile a project at `targetDir` from the given spec.
+ * Re-exports from @powerhousedao/ph-clint-dev/codegen with CLI_VERSION default.
  */
+import { generateProject as _generateProject, } from '@powerhousedao/ph-clint-dev/codegen';
+import { CLI_VERSION } from '../config.js';
 export async function generateProject(options) {
-    const { targetDir, spec } = options;
-    const warn = options.onWarn ?? (() => { });
-    const existingSpec = await readProjectSpec(targetDir);
-    const resolvedMode = resolveMode(options.mode ?? 'auto', existingSpec !== null);
-    // Flat → split migration, if needed. Runs BEFORE we compute planned files
-    // so the hash record and on-disk state are already in split-layout shape
-    // by the time the normal reconciliation runs.
-    let migrated = false;
-    if (resolvedMode === 'update' &&
-        existingSpec &&
-        !existingSpec.features.powerhouse.enabled &&
-        spec.features.powerhouse.enabled) {
-        await migrateFlatToSplit({
-            targetDir,
-            spec,
-            force: options.force,
-            onWarn: warn,
-        });
-        migrated = true;
-    }
-    // Dispatch to the mode-specific flow.
-    if (resolvedMode === 'create') {
-        return runCreate(options, warn);
-    }
-    return runUpdate(options, warn, migrated);
-}
-function resolveMode(requested, specExists) {
-    if (requested === 'create')
-        return 'create';
-    if (requested === 'update')
-        return 'update';
-    return specExists ? 'update' : 'create';
-}
-/** Build the list of files the new spec would emit, with their content. */
-function planFiles(spec, targetDir) {
-    const split = spec.features.powerhouse.enabled;
-    const cliDir = split ? path.join(targetDir, getCliFolderName(spec)) : targetDir;
-    const appDir = split ? path.join(targetDir, getAppFolderName(spec)) : null;
-    const planned = [];
-    for (const builder of CLI_FILE_BUILDERS) {
-        const content = builder.build(spec);
-        if (content === null)
-            continue;
-        const abs = path.join(cliDir, builder.relativePath);
-        planned.push({
-            relativePath: path.relative(targetDir, abs),
-            absolutePath: abs,
-            content,
-            initOnly: builder.initOnly,
-        });
-    }
-    // Project-root README — always at the top level.
-    const readmeAbs = path.join(targetDir, 'README.md');
-    planned.push({
-        relativePath: 'README.md',
-        absolutePath: readmeAbs,
-        content: buildReadme(spec),
+    return _generateProject({
+        ...options,
+        context: options.context ?? { toolVersion: CLI_VERSION },
     });
-    // Split-layout only: root package.json + app placeholder files.
-    if (split && appDir) {
-        const rootPkg = path.join(targetDir, 'package.json');
-        planned.push({
-            relativePath: 'package.json',
-            absolutePath: rootPkg,
-            content: buildRootPackageJson(spec),
-        });
-        const publishConfig = path.join(targetDir, 'publish.config.ts');
-        planned.push({
-            relativePath: 'publish.config.ts',
-            absolutePath: publishConfig,
-            content: buildPublishConfigTs(spec),
-        });
-        const appGitkeep = path.join(appDir, '.gitkeep');
-        planned.push({
-            relativePath: path.relative(targetDir, appGitkeep),
-            absolutePath: appGitkeep,
-            content: '',
-        });
-        const appReadme = path.join(appDir, 'README.md');
-        planned.push({
-            relativePath: path.relative(targetDir, appReadme),
-            absolutePath: appReadme,
-            content: buildAppReadmeContent(spec),
-        });
-        // Top-level barrel for the reactor package — lets impl code import from
-        // `{name}-app` instead of drilling into `document-models/<slug>/v1/gen`.
-        const appIndex = buildAppIndexTs(spec);
-        if (appIndex !== null) {
-            const appIndexAbs = path.join(appDir, 'index.ts');
-            planned.push({
-                relativePath: path.relative(targetDir, appIndexAbs),
-                absolutePath: appIndexAbs,
-                content: appIndex,
-            });
-        }
-    }
-    return { planned, cliDir, appDir };
-}
-function buildAppReadmeContent(spec) {
-    return [
-        `# ${spec.name}-app`,
-        '',
-        'Powerhouse reactor-package for this project. Scaffold it with:',
-        '',
-        '```sh',
-        `cd ${spec.name}-app`,
-        'ph init',
-        '```',
-        '',
-        'Then run `pnpm install` at the project root.',
-        '',
-    ].join('\n');
-}
-/** Create mode — empty target dir, write everything fresh. */
-async function runCreate(options, _warn) {
-    const { targetDir, spec } = options;
-    if (!options.allowNonEmpty) {
-        const empty = await isDirEmptyEnough(targetDir);
-        if (!empty) {
-            throw new Error(`target directory ${targetDir} is not empty (pass allowNonEmpty or --force to override)`);
-        }
-    }
-    const { planned, cliDir, appDir } = planFiles(spec, targetDir);
-    const hashes = {};
-    const files = [];
-    for (const p of planned) {
-        await writeFileEnsuringDir(p.absolutePath, p.content);
-        hashes[p.relativePath] = hashContent(p.content);
-        files.push({ absolutePath: p.absolutePath, relativePath: p.relativePath });
-    }
-    await writeProjectSpec(targetDir, spec);
-    files.push({
-        absolutePath: getSpecPath(targetDir),
-        relativePath: path.relative(targetDir, getSpecPath(targetDir)),
-    });
-    await writeHashes(targetDir, hashes);
-    return {
-        mode: 'create',
-        files,
-        skipped: [],
-        deleted: [],
-        migrated: false,
-        cliDir,
-        appDir,
-    };
-}
-/** Update mode — reconcile against an existing project. */
-async function runUpdate(options, warn, migrated) {
-    const { targetDir, spec } = options;
-    const force = !!options.force;
-    const { planned, cliDir, appDir } = planFiles(spec, targetDir);
-    const plannedByKey = new Map(planned.map((p) => [p.relativePath, p]));
-    const previous = await readHashes(targetDir);
-    const next = {};
-    const files = [];
-    const skipped = [];
-    const deleted = [];
-    // Step 1: write / patch / skip each planned file.
-    for (const p of planned) {
-        if (p.initOnly) {
-            // User-owned files (e.g. `src/framework.ts` with its `configSchema`)
-            // are emitted only on create. In update mode we never overwrite them
-            // and never re-create them if missing — the user may have deliberately
-            // deleted or inlined them. Keep whatever hash the previous run stored
-            // so the deletion pass (step 2) still considers them "ours".
-            const stored = previous[p.relativePath];
-            if (stored !== undefined)
-                next[p.relativePath] = stored;
-            continue;
-        }
-        const existing = await hashFile(p.absolutePath);
-        if (existing === null) {
-            // Not yet on disk — fresh write.
-            await writeFileEnsuringDir(p.absolutePath, p.content);
-            next[p.relativePath] = hashContent(p.content);
-            files.push({
-                absolutePath: p.absolutePath,
-                relativePath: p.relativePath,
-            });
-            continue;
-        }
-        // File exists. Decide how to update it.
-        if (hasMarkers(p.content)) {
-            const existingContent = await fs.readFile(p.absolutePath, 'utf8');
-            const patched = hasMarkers(existingContent)
-                ? spliceMarkerRegions(existingContent, p.content)
-                : p.content;
-            if (patched === existingContent) {
-                // No-op: regions already match.
-                next[p.relativePath] = hashContent(patched);
-                continue;
-            }
-            await writeFileEnsuringDir(p.absolutePath, patched);
-            next[p.relativePath] = hashContent(patched);
-            files.push({
-                absolutePath: p.absolutePath,
-                relativePath: p.relativePath,
-            });
-            continue;
-        }
-        // No markers — hash-protected overwrite.
-        const stored = previous[p.relativePath];
-        const pristine = stored !== undefined && stored === existing;
-        if (!pristine && !force) {
-            // User edited a managed file. Leave it alone.
-            warn(`skipped ${p.relativePath} — modified since last generation. Use --force to overwrite.`);
-            skipped.push({
-                absolutePath: p.absolutePath,
-                relativePath: p.relativePath,
-            });
-            // Preserve the previous hash so the file stays on our ledger.
-            if (stored !== undefined)
-                next[p.relativePath] = stored;
-            continue;
-        }
-        if (existing === hashContent(p.content)) {
-            // Already up to date.
-            next[p.relativePath] = existing;
-            continue;
-        }
-        await writeFileEnsuringDir(p.absolutePath, p.content);
-        next[p.relativePath] = hashContent(p.content);
-        files.push({
-            absolutePath: p.absolutePath,
-            relativePath: p.relativePath,
-        });
-    }
-    // Step 2: delete files that the new spec no longer emits, IF we still
-    // recognise their content (hash match). Otherwise warn and keep.
-    for (const [relPath, storedHash] of Object.entries(previous)) {
-        if (plannedByKey.has(relPath))
-            continue;
-        const abs = path.join(targetDir, relPath);
-        const onDisk = await hashFile(abs);
-        if (onDisk === null)
-            continue; // already gone
-        if (onDisk !== storedHash && !force) {
-            warn(`kept ${relPath} — modified since last generation; new spec no longer emits it.`);
-            next[relPath] = storedHash;
-            continue;
-        }
-        await fs.rm(abs, { force: true });
-        deleted.push({ absolutePath: abs, relativePath: relPath });
-    }
-    await writeProjectSpec(targetDir, spec);
-    await writeHashes(targetDir, next);
-    return {
-        mode: 'update',
-        files,
-        skipped,
-        deleted,
-        migrated,
-        cliDir,
-        appDir,
-    };
 }

package/dist/codegen/scaffold.d.ts

@@ -1,4 +1,13 @@
 import type { ClintProjectSpec } from '../spec/types.js';
+import type { ProcessRunOptions } from '@powerhousedao/ph-clint';
+/**
+ * Signature for the subprocess runner — matches CommandContext.runProcess.
+ */
+type RunProcess = (command: string, opts?: Omit<ProcessRunOptions, 'onOutput'>) => Promise<{
+    success: boolean;
+    output: string;
+}>;
+export type { RunProcess };
 export interface PhInitOptions {
     /** Absolute path to the project root. */
     targetDir: string;
@@ -9,22 +18,51 @@ export interface PhInitOptions {
     log?: (msg: string) => void;
     /** Override `ph` binary name (for tests). */
     binName?: string;
-    /** Stdio passthrough (tests pass 'ignore'). */
-    stdio?: 'inherit' | 'ignore';
+    /** Subprocess runner — matches CommandContext.runProcess. */
+    runProcess: RunProcess;
+    /** Explicit Powerhouse version to pin `ph init` to (tag or semver). */
+    phVersion?: string;
 }
 export interface PhInitResult {
     ran: boolean;
     exitCode?: number;
     reason?: string;
 }
+/**
+ * Detect the installed `ph` CLI version by parsing `ph --version` output.
+ * Returns the version string (e.g. '6.0.0-dev.194') or undefined if
+ * detection fails.
+ */
+export declare function getPhVersion(binName: string): string | undefined;
 export declare function runPhInit(options: PhInitOptions): Promise<PhInitResult>;
+/**
+ * Patch the app `package.json` name to the scoped form (`@scope/name-app`).
+ * Called after `ph init` and after name/scope renames.
+ *
+ * Returns `true` if the file was actually changed.
+ */
+export declare function patchAppPackageName(appDir: string, spec: {
+    name: string;
+    scope?: string;
+}, log?: (msg: string) => void): Promise<boolean>;
+/**
+ * Run `ph install <packages> --local --pnpm` in the app directory to register
+ * external packages in `powerhouse.config.json`.
+ */
+export declare function runPhInstallPackages(options: {
+    appDir: string;
+    packages: string[];
+    log?: (msg: string) => void;
+    runProcess: RunProcess;
+}): Promise<boolean>;
 export interface PnpmInstallOptions {
     /** Directories to run `pnpm install` in, in order. */
     dirs: string[];
     log?: (msg: string) => void;
     /** Override `pnpm` binary name (for tests). */
     binName?: string;
-    stdio?: 'inherit' | 'ignore';
+    /** Subprocess runner — matches CommandContext.runProcess. */
+    runProcess: RunProcess;
 }
 export interface PnpmInstallResult {
     ran: string[];

package/dist/codegen/scaffold.js

@@ -7,32 +7,123 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { hasCommandOnPath, runCommand } from './exec.js';
+import { execFileSync } from 'node:child_process';
+import { hasCommandOnPath } from './exec.js';
+/**
+ * Detect the installed `ph` CLI version by parsing `ph --version` output.
+ * Returns the version string (e.g. '6.0.0-dev.194') or undefined if
+ * detection fails.
+ */
+export function getPhVersion(binName) {
+    try {
+        const output = execFileSync(binName, ['--version'], {
+            encoding: 'utf-8',
+            timeout: 5_000,
+        });
+        const match = output.match(/PH CMD version:\s*(\S+)/);
+        return match?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function runPhInit(options) {
     const log = options.log ?? (() => { });
     const binName = options.binName ?? 'ph';
     const appFolder = path.basename(options.appDir);
+    // Guard: never re-init an already-initialized app directory.
+    try {
+        await fs.access(path.join(options.appDir, 'package.json'));
+        log(`App directory ${appFolder} already initialized — skipping ph init.`);
+        return { ran: false, reason: 'already-initialized' };
+    }
+    catch {
+        // No package.json — proceed with init.
+    }
     if (!(await hasCommandOnPath(binName))) {
         log(`Skipping \`${binName} init\` — \`${binName}\` is not on PATH. ` +
             `Install @powerhousedao/ph-cli and re-run manually inside ${appFolder}/.`);
         return { ran: false, reason: 'ph-not-on-path' };
     }
+    // Pin ph init to the same version as the installed ph CLI, so the
+    // generated app uses matching Powerhouse packages.
+    const phVersion = options.phVersion ?? getPhVersion(binName);
+    const tags = ['dev', 'staging', 'latest'];
+    const versionArgs = phVersion
+        ? tags.includes(phVersion)
+            ? [`--${phVersion}`]
+            : ['--version', phVersion]
+        : ['--dev']; // fallback if detection fails
     // `ph init {name}` creates a fresh directory beside the cwd. Our generator
     // placed a `.gitkeep` + README.md placeholder there; clear it out so
     // ph init has a blank slate to work with.
     await fs.rm(options.appDir, { recursive: true, force: true });
-    log(`Running \`${binName} init ${appFolder}\` in ${options.targetDir} …`);
-    const result = await runCommand(binName, [
-        'init',
-        appFolder,
-        '--pnpm',
-        '--dev',
-    ], { cwd: options.targetDir, stdio: options.stdio ?? 'inherit' });
-    if (result.exitCode !== 0) {
-        log(`\`${binName} init\` exited with code ${result.exitCode}. ` +
+    const args = ['init', appFolder, ...versionArgs, '--pnpm'];
+    log(`Running \`${binName} init ${appFolder}\` (version: ${phVersion ?? 'auto'}) in ${options.targetDir} …`);
+    const result = await options.runProcess(`${binName} ${args.join(' ')}`, {
+        cwd: options.targetDir,
+        timeout: 300_000,
+    });
+    const exitCode = result.success ? 0 : 1;
+    if (!result.success) {
+        log(`\`${binName} init\` failed. ` +
             'You can re-run it manually after resolving the issue.');
     }
-    return { ran: true, exitCode: result.exitCode };
+    await patchScopedName(options, appFolder, log);
+    return { ran: true, exitCode };
+}
+/**
+ * Patch the app `package.json` name to the scoped form (`@scope/name-app`).
+ * Called after `ph init` and after name/scope renames.
+ *
+ * Returns `true` if the file was actually changed.
+ */
+export async function patchAppPackageName(appDir, spec, log) {
+    const appFolder = path.basename(appDir);
+    const scopedName = spec.scope
+        ? `${spec.scope}/${appFolder}`
+        : appFolder;
+    const appPkgJsonPath = path.join(appDir, 'package.json');
+    try {
+        const raw = await fs.readFile(appPkgJsonPath, 'utf8');
+        const pkg = JSON.parse(raw);
+        if (pkg.name !== scopedName) {
+            pkg.name = scopedName;
+            if (spec.scope) {
+                pkg.publishConfig = { access: 'public' };
+            }
+            await fs.writeFile(appPkgJsonPath, JSON.stringify(pkg, null, 2) + '\n');
+            log?.(`Patched app package name to ${scopedName}`);
+            return true;
+        }
+        return false;
+    }
+    catch (err) {
+        log?.(`Warning: could not patch app package name: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+async function patchScopedName(options, _appFolder, log) {
+    await patchAppPackageName(options.appDir, options.spec, log);
+}
+/**
+ * Run `ph install <packages> --local --pnpm` in the app directory to register
+ * external packages in `powerhouse.config.json`.
+ */
+export async function runPhInstallPackages(options) {
+    const { appDir, packages, log = () => { }, runProcess } = options;
+    const binName = 'ph';
+    if (!(await hasCommandOnPath(binName))) {
+        log(`Skipping — \`${binName}\` is not on PATH.`);
+        return false;
+    }
+    const args = ['install', ...packages, '--local', '--pnpm'];
+    log(`Running \`${binName} install ${packages.join(' ')} --local\` in ${path.basename(appDir)} …`);
+    const result = await runProcess(`${binName} ${args.join(' ')}`, {
+        cwd: appDir,
+        timeout: 300_000,
+    });
+    return result.success;
 }
 export async function runPnpmInstall(options) {
     const log = options.log ?? (() => { });
@@ -45,14 +136,13 @@ export async function runPnpmInstall(options) {
     const ran = [];
     for (const dir of options.dirs) {
         log(`Running \`${binName} install\` in ${dir} …`);
-        const result = await runCommand(binName, ['install'], {
+        const result = await options.runProcess(`${binName} install`, {
             cwd: dir,
-            stdio: options.stdio ?? 'inherit',
+            timeout: 300_000,
         });
-        if (result.exitCode !== 0) {
-            log(`\`${binName} install\` exited with code ${result.exitCode} in ${dir}. ` +
+        if (!result.success) {
+            log(`\`${binName} install\` failed in ${dir}. ` +
                 'Retry manually once the underlying issue is resolved.');
-            // Don't abort the whole chain — subsequent dirs may still work.
         }
         ran.push(dir);
     }