@powerhousedao/ph-clint-cli 0.1.0-dev.0

package/dist/codegen/index.d.ts

@@ -0,0 +1,39 @@
+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.
+ */
+export declare function generateProject(options: GenerateProjectOptions): Promise<GenerateProjectResult>;

package/dist/codegen/index.js

@@ -0,0 +1,292 @@
+/**
+ * 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, buildAppIndexTs, } from './builders/index.js';
+/**
+ * Generate / reconcile a project at `targetDir` from the given spec.
+ */
+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),
+    });
+    // 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 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/markers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Marker-region parsing for `@clint:begin {name}` / `@clint:end {name}`
+ * comment blocks. Used in delta mode to splice freshly-generated regions
+ * into an existing, user-edited file while preserving everything outside
+ * the markers.
+ *
+ * The only syntactic requirement is that the markers are on their own lines,
+ * as ordinary line comments (`//`). Indentation is preserved for output.
+ */
+export interface MarkerRegion {
+    /** Region identifier (the text after `@clint:begin`). */
+    name: string;
+    /** Lines *between* the begin and end markers (exclusive). */
+    body: string[];
+    /** Indentation of the begin line — used when rewriting. */
+    indent: string;
+    /** Line index of the begin marker in the source. */
+    beginLine: number;
+    /** Line index of the end marker in the source. */
+    endLine: number;
+}
+/**
+ * Parse every `@clint:begin {name}` … `@clint:end {name}` block in `source`.
+ * Throws if markers are mismatched or unclosed.
+ */
+export declare function parseMarkerRegions(source: string): MarkerRegion[];
+/**
+ * Replace every region in `target` that also exists in `source` with the
+ * `source` region's body. Leaves regions present in `target` but not `source`
+ * untouched. Ignores regions in `source` missing from `target`.
+ *
+ * Returns the rewritten file content.
+ */
+export declare function spliceMarkerRegions(target: string, source: string): string;
+/** Convenience — true if `content` contains at least one `@clint:begin`. */
+export declare function hasMarkers(content: string): boolean;

package/dist/codegen/markers.js

@@ -0,0 +1,86 @@
+/**
+ * Marker-region parsing for `@clint:begin {name}` / `@clint:end {name}`
+ * comment blocks. Used in delta mode to splice freshly-generated regions
+ * into an existing, user-edited file while preserving everything outside
+ * the markers.
+ *
+ * The only syntactic requirement is that the markers are on their own lines,
+ * as ordinary line comments (`//`). Indentation is preserved for output.
+ */
+const BEGIN_RE = /^([ \t]*)\/\/\s*@clint:begin\s+(\S+)\s*$/;
+const END_RE = /^([ \t]*)\/\/\s*@clint:end\s+(\S+)\s*$/;
+/**
+ * Parse every `@clint:begin {name}` … `@clint:end {name}` block in `source`.
+ * Throws if markers are mismatched or unclosed.
+ */
+export function parseMarkerRegions(source) {
+    const lines = source.split('\n');
+    const regions = [];
+    let open = null;
+    let bodyStart = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const begin = BEGIN_RE.exec(line);
+        if (begin) {
+            if (open) {
+                throw new Error(`nested @clint:begin ${begin[2]} at line ${i + 1} while ${open.name} is still open`);
+            }
+            open = { name: begin[2], indent: begin[1], beginLine: i };
+            bodyStart = i + 1;
+            continue;
+        }
+        const end = END_RE.exec(line);
+        if (end) {
+            if (!open) {
+                throw new Error(`@clint:end ${end[2]} at line ${i + 1} without matching begin`);
+            }
+            if (open.name !== end[2]) {
+                throw new Error(`@clint:end ${end[2]} at line ${i + 1} does not match open @clint:begin ${open.name}`);
+            }
+            regions.push({
+                name: open.name,
+                body: lines.slice(bodyStart, i),
+                indent: open.indent,
+                beginLine: open.beginLine,
+                endLine: i,
+            });
+            open = null;
+        }
+    }
+    if (open) {
+        throw new Error(`unterminated @clint:begin ${open.name}`);
+    }
+    return regions;
+}
+/**
+ * Replace every region in `target` that also exists in `source` with the
+ * `source` region's body. Leaves regions present in `target` but not `source`
+ * untouched. Ignores regions in `source` missing from `target`.
+ *
+ * Returns the rewritten file content.
+ */
+export function spliceMarkerRegions(target, source) {
+    const sourceRegions = parseMarkerRegions(source);
+    const sourceByName = new Map();
+    for (const r of sourceRegions)
+        sourceByName.set(r.name, r);
+    const targetRegions = parseMarkerRegions(target);
+    if (targetRegions.length === 0)
+        return target;
+    const lines = target.split('\n');
+    // Apply replacements from last to first so line indices stay valid.
+    const sorted = [...targetRegions].sort((a, b) => b.beginLine - a.beginLine);
+    for (const region of sorted) {
+        const fresh = sourceByName.get(region.name);
+        if (!fresh)
+            continue;
+        // Replace the body lines (exclusive of the begin/end marker lines).
+        const bodyLen = region.endLine - region.beginLine - 1;
+        lines.splice(region.beginLine + 1, bodyLen, ...fresh.body);
+    }
+    return lines.join('\n');
+}
+/** Convenience — true if `content` contains at least one `@clint:begin`. */
+export function hasMarkers(content) {
+    return /^[ \t]*\/\/\s*@clint:begin\s+\S+\s*$/m.test(content);
+}

package/dist/codegen/migrate/flat-to-split.d.ts

@@ -0,0 +1,15 @@
+import { type ClintProjectSpec } from '../../spec/types.js';
+export interface FlatToSplitOptions {
+    targetDir: string;
+    spec: ClintProjectSpec;
+    /** Bypass the git-dirty guard. */
+    force?: boolean;
+    /** Optional warn sink for non-fatal messages. */
+    onWarn?: (msg: string) => void;
+}
+export interface FlatToSplitResult {
+    movedEntries: string[];
+    cliDir: string;
+    appDir: string;
+}
+export declare function migrateFlatToSplit(options: FlatToSplitOptions): Promise<FlatToSplitResult>;

package/dist/codegen/migrate/flat-to-split.js

@@ -0,0 +1,119 @@
+/**
+ * One-shot migration that runs when a project's spec flips
+ * `features.powerhouse.enabled` from `false` to `true`. It reshapes the
+ * on-disk layout from flat (everything at the project root) to split
+ * (`{name}-cli/` + `{name}-app/` siblings).
+ *
+ * The follow-up update-mode regeneration then fills in the correct content
+ * for each file in its new location — so this migration only moves bytes
+ * around. Content updates belong to the generator.
+ *
+ * `node_modules` is deliberately NOT moved — pnpm `file:` protocol uses
+ * symlinks that do not survive a cross-directory rename cleanly. Callers
+ * should re-run `pnpm install` after the migration.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { getAppFolderName, getCliFolderName, } from '../../spec/types.js';
+import { readHashes, writeHashes } from '../hashes.js';
+/** Entries we never move during a flat → split migration. */
+function isUnmovable(entry, cliFolder, appFolder) {
+    if (entry === '.git')
+        return true;
+    if (entry === '.ph')
+        return true;
+    if (entry === 'README.md')
+        return true;
+    if (entry === 'node_modules')
+        return true;
+    if (entry === cliFolder)
+        return true;
+    if (entry === appFolder)
+        return true;
+    return false;
+}
+/**
+ * Guard: if the target is a git repo with a dirty working tree, refuse to
+ * migrate unless `force`. We never want to discard uncommitted edits.
+ * Resolves to `null` when the dir is not a git repo.
+ */
+async function gitDirty(dir) {
+    return new Promise((resolve) => {
+        const child = spawn('git', ['status', '--porcelain'], {
+            cwd: dir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let out = '';
+        child.stdout?.on('data', (d) => {
+            out += d.toString();
+        });
+        child.once('error', () => resolve(null));
+        child.once('close', (code) => {
+            if (code !== 0)
+                resolve(null);
+            else
+                resolve(out.trim() || null);
+        });
+    });
+}
+export async function migrateFlatToSplit(options) {
+    const { targetDir, spec } = options;
+    const cliFolder = getCliFolderName(spec);
+    const appFolder = getAppFolderName(spec);
+    const cliDir = path.join(targetDir, cliFolder);
+    const appDir = path.join(targetDir, appFolder);
+    if (!options.force) {
+        const dirty = await gitDirty(targetDir);
+        if (dirty) {
+            throw new Error(`refusing to migrate flat → split: ${targetDir} has uncommitted changes.\n` +
+                'Commit or stash first, or re-run with --force.');
+        }
+    }
+    // Create the CLI destination. If it already exists and is non-empty we
+    // treat that as a malformed state and bail — a previous migration probably
+    // got interrupted.
+    await fs.mkdir(cliDir, { recursive: true });
+    const cliExisting = await fs.readdir(cliDir);
+    if (cliExisting.length > 0) {
+        throw new Error(`cannot migrate: ${cliDir} already exists and is non-empty. ` +
+            'Resolve manually before re-running.');
+    }
+    const entries = await fs.readdir(targetDir);
+    const moved = [];
+    for (const entry of entries) {
+        if (isUnmovable(entry, cliFolder, appFolder)) {
+            if (entry === 'node_modules' && options.onWarn) {
+                options.onWarn('skipped node_modules during flat → split migration; re-run `pnpm install`.');
+            }
+            continue;
+        }
+        const src = path.join(targetDir, entry);
+        const dst = path.join(cliDir, entry);
+        await fs.rename(src, dst);
+        moved.push(entry);
+    }
+    // Rekey stored hashes so they still line up with the moved paths.
+    await rekeyHashes(targetDir, moved, cliFolder);
+    // Create the app folder with a placeholder so tooling (git, `ph init`) can
+    // find it. The generator and/or `ph init` fills in the real contents.
+    await fs.mkdir(appDir, { recursive: true });
+    return { movedEntries: moved, cliDir, appDir };
+}
+async function rekeyHashes(targetDir, movedEntries, cliFolder) {
+    const before = await readHashes(targetDir);
+    if (Object.keys(before).length === 0)
+        return;
+    const movedSet = new Set(movedEntries);
+    const after = {};
+    for (const [key, hash] of Object.entries(before)) {
+        const top = key.split(/[\\/]/)[0];
+        if (movedSet.has(top)) {
+            after[path.posix.join(cliFolder, key)] = hash;
+        }
+        else {
+            after[key] = hash;
+        }
+    }
+    await writeHashes(targetDir, after);
+}

package/dist/codegen/scaffold.d.ts

@@ -0,0 +1,34 @@
+import type { ClintProjectSpec } from '../spec/types.js';
+export interface PhInitOptions {
+    /** Absolute path to the project root. */
+    targetDir: string;
+    /** Absolute path to `{targetDir}/{name}-app` (exists with our placeholder). */
+    appDir: string;
+    spec: ClintProjectSpec;
+    /** Logger; defaults to noop. */
+    log?: (msg: string) => void;
+    /** Override `ph` binary name (for tests). */
+    binName?: string;
+    /** Stdio passthrough (tests pass 'ignore'). */
+    stdio?: 'inherit' | 'ignore';
+}
+export interface PhInitResult {
+    ran: boolean;
+    exitCode?: number;
+    reason?: string;
+}
+export declare function runPhInit(options: PhInitOptions): Promise<PhInitResult>;
+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';
+}
+export interface PnpmInstallResult {
+    ran: string[];
+    skipped: string[];
+    reason?: string;
+}
+export declare function runPnpmInstall(options: PnpmInstallOptions): Promise<PnpmInstallResult>;

package/dist/codegen/scaffold.js

@@ -0,0 +1,60 @@
+/**
+ * Post-generation side-effects: invoke `ph init` to fill in the reactor
+ * package skeleton, and run `pnpm install` in the relevant sub-projects.
+ *
+ * Both steps are opt-out (flags on the init command) and both tolerate
+ * missing binaries — they never fail the init flow, only emit warnings.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { hasCommandOnPath, runCommand } from './exec.js';
+export async function runPhInit(options) {
+    const log = options.log ?? (() => { });
+    const binName = options.binName ?? 'ph';
+    const appFolder = path.basename(options.appDir);
+    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' };
+    }
+    // `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}. ` +
+            'You can re-run it manually after resolving the issue.');
+    }
+    return { ran: true, exitCode: result.exitCode };
+}
+export async function runPnpmInstall(options) {
+    const log = options.log ?? (() => { });
+    const binName = options.binName ?? 'pnpm';
+    if (!(await hasCommandOnPath(binName))) {
+        log(`Skipping \`${binName} install\` — \`${binName}\` is not on PATH. ` +
+            'Install pnpm and re-run manually.');
+        return { ran: [], skipped: options.dirs, reason: 'pnpm-not-on-path' };
+    }
+    const ran = [];
+    for (const dir of options.dirs) {
+        log(`Running \`${binName} install\` in ${dir} …`);
+        const result = await runCommand(binName, ['install'], {
+            cwd: dir,
+            stdio: options.stdio ?? 'inherit',
+        });
+        if (result.exitCode !== 0) {
+            log(`\`${binName} install\` exited with code ${result.exitCode} in ${dir}. ` +
+                'Retry manually once the underlying issue is resolved.');
+            // Don't abort the whole chain — subsequent dirs may still work.
+        }
+        ran.push(dir);
+    }
+    return { ran, skipped: [] };
+}