@powerhousedao/ph-clint-cli 0.1.0-dev.86 → 0.1.0-dev.88

package/dist/codegen/builders/tsconfig-json.js

@@ -0,0 +1,22 @@
+/**
+ * Builds `tsconfig.json` for the CLI.
+ */
+export function buildTsconfigJson() {
+    const tsconfig = {
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'Node16',
+            moduleResolution: 'Node16',
+            outDir: 'dist',
+            rootDir: 'src',
+            strict: true,
+            isolatedModules: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            declaration: true,
+            types: ['node'],
+        },
+        include: ['src'],
+    };
+    return JSON.stringify(tsconfig, null, 2) + '\n';
+}

package/dist/codegen/exec.d.ts

@@ -0,0 +1,2 @@
+/** Returns true if `command` is on PATH. */
+export declare function hasCommandOnPath(command: string): Promise<boolean>;

package/dist/codegen/exec.js

@@ -0,0 +1,14 @@
+/**
+ * Small helpers for invoking external commands during code generation.
+ */
+import { spawn } from 'node:child_process';
+/** Returns true if `command` is on PATH. */
+export async function hasCommandOnPath(command) {
+    return new Promise((resolve) => {
+        const child = spawn(process.platform === 'win32' ? 'where' : 'which', [command], {
+            stdio: 'ignore',
+        });
+        child.once('error', () => resolve(false));
+        child.once('close', (code) => resolve(code === 0));
+    });
+}

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/hashes.d.ts

@@ -0,0 +1,6 @@
+export type HashRecord = Record<string, string>;
+export declare function getHashesPath(targetDir: string): string;
+export declare function hashContent(content: string): string;
+export declare function hashFile(filePath: string): Promise<string | null>;
+export declare function readHashes(targetDir: string): Promise<HashRecord>;
+export declare function writeHashes(targetDir: string, hashes: HashRecord): Promise<void>;

package/dist/codegen/hashes.js

@@ -0,0 +1,60 @@
+/**
+ * Per-file content hashes written by the generator so subsequent runs can
+ * detect whether a previously-generated file has been hand-edited.
+ *
+ * Stored at `{targetDir}/.ph/ph-clint-cli/.hashes.json` alongside the project
+ * spec. Keys are paths relative to the project root.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const HASHES_DIR = path.join('.ph', 'ph-clint-cli');
+const HASHES_FILE = '.hashes.json';
+export function getHashesPath(targetDir) {
+    return path.join(targetDir, HASHES_DIR, HASHES_FILE);
+}
+export function hashContent(content) {
+    return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function isEnoent(err) {
+    return (!!err &&
+        typeof err === 'object' &&
+        'code' in err &&
+        err.code === 'ENOENT');
+}
+export async function hashFile(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        return hashContent(content);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return null;
+        throw err;
+    }
+}
+export async function readHashes(targetDir) {
+    try {
+        const raw = await fs.readFile(getHashesPath(targetDir), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return {};
+        throw err;
+    }
+}
+export async function writeHashes(targetDir, hashes) {
+    const file = getHashesPath(targetDir);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    // Sort keys for stable output across runs.
+    const sorted = {};
+    for (const key of Object.keys(hashes).sort()) {
+        sorted[key] = hashes[key];
+    }
+    await fs.writeFile(file, JSON.stringify(sorted, null, 2) + '\n', 'utf8');
+}

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,72 @@
+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;
+    /** 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;
+    /** 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;
+    /** Subprocess runner — matches CommandContext.runProcess. */
+    runProcess: RunProcess;
+}
+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,150 @@
+/**
+ * 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 { 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 });
+    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.');
+    }
+    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 ?? (() => { });
+    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 options.runProcess(`${binName} install`, {
+            cwd: dir,
+            timeout: 300_000,
+        });
+        if (!result.success) {
+            log(`\`${binName} install\` failed in ${dir}. ` +
+                'Retry manually once the underlying issue is resolved.');
+        }
+        ran.push(dir);
+    }
+    return { ran, skipped: [] };
+}

package/dist/codegen/write.d.ts

@@ -0,0 +1,6 @@
+export declare function writeFileEnsuringDir(filePath: string, content: string): Promise<void>;
+/**
+ * Returns true if the directory doesn't exist or only contains ignorable
+ * entries (`.git`, `.DS_Store`, `.ph/ph-clint-cli/project-spec.json`).
+ */
+export declare function isDirEmptyEnough(dir: string): Promise<boolean>;