@powerhousedao/ph-clint-cli 0.1.0-dev.6 → 0.1.0-dev.61

package/dist/codegen/builders/demo-agent-ts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Builds `src/agents/demo-agent.ts` — a deterministic echo agent fallback.
+ *
+ * Generated when `features.mastra.enabled` with full agent config so the real
+ * agent factory can fall back to demo mode when no API key is configured.
+ */
+import { type ClintProjectSpec } from '../../spec/types.js';
+export declare function buildDemoAgentTs(spec: ClintProjectSpec): string | null;

package/dist/codegen/builders/demo-agent-ts.js

@@ -0,0 +1,50 @@
+export function buildDemoAgentTs(spec) {
+    const { mastra } = spec.features;
+    // Only needed alongside the real agent (which imports it)
+    if (!mastra.enabled || !mastra.agentId || mastra.models.length === 0)
+        return null;
+    const agentId = mastra.agentId;
+    const agentName = mastra.agentName ?? agentId;
+    const agentDescription = mastra.agentDescription;
+    const agentImage = mastra.agentImage;
+    return [
+        "import type { AgentProvider, StreamChunk } from '@powerhousedao/ph-clint';",
+        '',
+        '/**',
+        ' * Demo agent — deterministic echo responses without an API key.',
+        ' *',
+        ' * Echoes user prompts with conversation tracking per thread.',
+        ' */',
+        'export function createDemoAgent(): AgentProvider {',
+        '  const conversations = new Map<string, string[]>();',
+        '',
+        '  return {',
+        `    id: '${agentId}',`,
+        `    name: '${agentName}',`,
+        ...(agentDescription ? [`    description: ${JSON.stringify(agentDescription)},`] : []),
+        ...(agentImage ? [`    image: ${JSON.stringify(agentImage)},`] : []),
+        '    async *stream(prompt, opts) {',
+        "      const threadId = opts?.threadId ?? 'default';",
+        '      if (!conversations.has(threadId)) {',
+        '        conversations.set(threadId, []);',
+        '      }',
+        '      const history = conversations.get(threadId)!;',
+        '      history.push(prompt);',
+        '',
+        '      const turnCount = history.length;',
+        '      if (turnCount > 1) {',
+        '        yield {',
+        "          type: 'text-delta',",
+        '          text: `I understand you\'re continuing our conversation (turn ${turnCount}). `,',
+        '        } satisfies StreamChunk;',
+        '      }',
+        '      yield {',
+        "        type: 'text-delta',",
+        '        text: `You said: "${prompt}". I\'m the demo agent — set an API key for real LLM responses.`,',
+        '      } satisfies StreamChunk;',
+        '    },',
+        '  };',
+        '}',
+        '',
+    ].join('\n');
+}

package/dist/codegen/builders/eslint-config-js.d.ts

@@ -1,4 +1,4 @@
 /**
- * Builds `eslint.config.js` for the CLI — placeholder flat config.
+ * Builds `eslint.config.js` for the CLI — minimal TypeScript-ESLint config.
  */
 export declare function buildEslintConfigJs(): string;

package/dist/codegen/builders/eslint-config-js.js

@@ -1,12 +1,15 @@
 /**
- * Builds `eslint.config.js` for the CLI — placeholder flat config.
+ * Builds `eslint.config.js` for the CLI — minimal TypeScript-ESLint config.
  */
 export function buildEslintConfigJs() {
     return [
         '// @clint:begin eslint',
-        '// Placeholder ESLint flat config — replaced by codegen when the',
-        "// project's lint stack is configured.",
-        'export default [];',
+        "import tseslint from 'typescript-eslint';",
+        '',
+        'export default tseslint.config(',
+        '  tseslint.configs.recommended,',
+        "  { ignores: ['dist/', 'gen/', 'coverage/'] },",
+        ');',
         '// @clint:end eslint',
         '',
     ].join('\n');

package/dist/codegen/builders/framework-gen-ts.d.ts

@@ -1,17 +1,22 @@
 /**
  * Builds `src/framework.gen.ts` — the fully machine-owned half of the
  * typed-binding split. Regenerated on every `init` and `update`; holds the
- * `defineRegistry([...] as const)` call that describes which document models
+ * `defineRegistry([...])` call that describes which document models
  * are bound into `framework.ts`'s typed factories.
  *
- * Kept deliberately small: this file exports only `registry` and the
- * `Registry` type. The `createTypes` call lives in `framework.ts` (the
- * user-owned half) so `configSchema` edits stay local and we avoid an import
- * cycle between the two files.
+ * Iterates all packages' document types. The app package's modules are
+ * imported from the local `{name}-app` package; external packages' modules
+ * are imported from their npm package name.
+ *
+ * Document type entries may be explicit IDs (`powerhouse/ph-clint-project`)
+ * or glob patterns (`*​/*`, `powerhouse/*`, `acme/doc-*`).  Explicit IDs
+ * produce static named imports; glob patterns import the package's
+ * `documentModels` array and filter at runtime so newly-added document
+ * models are picked up without a codegen re-run.
  *
  * Emitted only when Powerhouse is enabled — flat-layout impls have no
  * reactor package to import modules from and bind `createTypes` directly in
- * `framework.ts`. When Powerhouse is on but no `documentTypes` are declared,
+ * `framework.ts`. When Powerhouse is on but no document types are declared,
  * we still emit this file with an empty `defineRegistry([])` so impl code's
  * `import { registry } from './framework.gen.js'` keeps resolving across
  * regens.

package/dist/codegen/builders/framework-gen-ts.js

@@ -1,34 +1,64 @@
 /**
  * Builds `src/framework.gen.ts` — the fully machine-owned half of the
  * typed-binding split. Regenerated on every `init` and `update`; holds the
- * `defineRegistry([...] as const)` call that describes which document models
+ * `defineRegistry([...])` call that describes which document models
  * are bound into `framework.ts`'s typed factories.
  *
- * Kept deliberately small: this file exports only `registry` and the
- * `Registry` type. The `createTypes` call lives in `framework.ts` (the
- * user-owned half) so `configSchema` edits stay local and we avoid an import
- * cycle between the two files.
+ * Iterates all packages' document types. The app package's modules are
+ * imported from the local `{name}-app` package; external packages' modules
+ * are imported from their npm package name.
+ *
+ * Document type entries may be explicit IDs (`powerhouse/ph-clint-project`)
+ * or glob patterns (`*​/*`, `powerhouse/*`, `acme/doc-*`).  Explicit IDs
+ * produce static named imports; glob patterns import the package's
+ * `documentModels` array and filter at runtime so newly-added document
+ * models are picked up without a codegen re-run.
  *
  * Emitted only when Powerhouse is enabled — flat-layout impls have no
  * reactor package to import modules from and bind `createTypes` directly in
- * `framework.ts`. When Powerhouse is on but no `documentTypes` are declared,
+ * `framework.ts`. When Powerhouse is on but no document types are declared,
  * we still emit this file with an empty `defineRegistry([])` so impl code's
  * `import { registry } from './framework.gen.js'` keeps resolving across
  * regens.
  */
-import { getDocumentTypeModuleName, } from '../../spec/types.js';
-/** Local package name of the reactor package for this project. */
-function appPackageName(spec) {
-    return `${spec.name}-app`;
-}
+import { docTypeGlobToRegex, getAppPackageName, getDocumentTypeModuleName, getDocumentTypeSlug, isDocTypeGlob, phAtLeast, } from '../../spec/types.js';
 export function buildFrameworkGenTs(spec) {
-    if (!spec.features.powerhouse.enabled)
+    if (!phAtLeast(spec.features.powerhouse, 'Reactor'))
         return null;
-    const pkg = appPackageName(spec);
-    const entries = spec.documentTypes.map((docType) => ({
-        docType,
-        name: getDocumentTypeModuleName(docType),
-    }));
+    const appPkg = getAppPackageName(spec);
+    // Collect entries across packages. Each package may contribute both
+    // explicit named imports and glob-based runtime filters.
+    const entries = [];
+    let globCounter = 0;
+    for (const pkg of spec.packages) {
+        const isApp = pkg.packageName === appPkg;
+        // Collect glob patterns for this package (may be multiple).
+        const globs = pkg.documentTypes.filter(isDocTypeGlob);
+        const explicits = pkg.documentTypes.filter((dt) => !isDocTypeGlob(dt));
+        for (const docType of explicits) {
+            const slug = getDocumentTypeSlug(docType);
+            entries.push({
+                kind: 'explicit',
+                name: getDocumentTypeModuleName(docType),
+                importFrom: isApp ? appPkg : `${pkg.packageName}/document-models/${slug}`,
+            });
+        }
+        if (globs.length > 0) {
+            // Merge all globs for this package into a single regex alternation.
+            const combined = globs.length === 1
+                ? docTypeGlobToRegex(globs[0])
+                : globs.map((g) => `(?:${docTypeGlobToRegex(g)})`).join('|');
+            const alias = globCounter === 0 ? 'globModels' : `globModels${globCounter}`;
+            globCounter++;
+            entries.push({
+                kind: 'glob',
+                modelsAlias: alias,
+                importFrom: isApp ? appPkg : pkg.packageName,
+                regexSource: combined,
+            });
+        }
+    }
+    const hasGlobs = entries.some((e) => e.kind === 'glob');
     const lines = [];
     lines.push('/**');
     lines.push(' * THIS FILE IS GENERATED BY ph-clint-cli. DO NOT EDIT.');
@@ -38,24 +68,46 @@ export function buildFrameworkGenTs(spec) {
     lines.push(' * this file will be overwritten.');
     lines.push(' */');
     lines.push(`import { defineRegistry } from '@powerhousedao/ph-clint';`);
+    // Emit imports — named imports for explicit entries, documentModels for globs.
     for (const e of entries) {
-        lines.push(`import { ${e.name} } from '${pkg}';`);
+        if (e.kind === 'explicit') {
+            lines.push(`import { ${e.name} } from '${e.importFrom}';`);
+        }
+        else {
+            lines.push(`import { documentModels as ${e.modelsAlias} } from '${e.importFrom}';`);
+        }
     }
     lines.push('');
     lines.push('/**');
     lines.push(' * Typed document registry derived from the reactor package\'s document models.');
-    lines.push(' * Regenerated whenever the spec\'s `documentTypes` list changes.');
+    lines.push(' * Regenerated whenever the spec\'s packages or document types change.');
     lines.push(' */');
     if (entries.length === 0) {
         lines.push('export const registry = defineRegistry([] as const);');
     }
-    else {
+    else if (!hasGlobs) {
+        // Pure explicit — use `as const` for full type inference.
         lines.push('export const registry = defineRegistry([');
         for (const e of entries) {
-            lines.push(`  ${e.name},`);
+            if (e.kind === 'explicit') {
+                lines.push(`  ${e.name},`);
+            }
         }
         lines.push('] as const);');
     }
+    else {
+        // Mix of explicit + glob — runtime filter loses `as const` inference.
+        lines.push('export const registry = defineRegistry([');
+        for (const e of entries) {
+            if (e.kind === 'explicit') {
+                lines.push(`  ${e.name},`);
+            }
+            else {
+                lines.push(`  ...${e.modelsAlias}.filter((m) => /${e.regexSource}/.test(m.documentModel.global.id)),`);
+            }
+        }
+        lines.push(']);');
+    }
     lines.push('');
     lines.push('export type Registry = typeof registry;');
     return lines.join('\n') + '\n';

package/dist/codegen/builders/framework-ts.js

@@ -1,6 +1,26 @@
+/**
+ * Builds `src/framework.ts` — the user-owned half of the typed-binding split.
+ *
+ * Emitted **only on create**. Once the file exists, codegen never overwrites
+ * it: users are expected to extend `configSchema` and `secretsSchema` here,
+ * and those edits must survive regens.
+ *
+ * Behavior differs by layout:
+ *
+ * - **Powerhouse enabled** — this file declares `configSchema`/`secretsSchema`
+ *   and re-exports `registry`, `defineCommand`, `defineTrigger`,
+ *   `defineService`, and `createDocumentChangeTrigger` from the companion
+ *   `framework.gen.ts`. Adding a document type to the spec regenerates
+ *   `framework.gen.ts`; this file keeps resolving its re-exports unchanged.
+ *
+ * - **Powerhouse disabled** — no reactor package exists to register modules
+ *   against, so this file binds `createTypes({ configSchema })` directly and
+ *   exports the typed factories from here. No `framework.gen.ts` is emitted.
+ */
+import { phAtLeast } from '../../spec/types.js';
 export function buildFrameworkTs(spec) {
     const { mastra, powerhouse } = spec.features;
-    const hasGen = powerhouse.enabled;
+    const hasGen = phAtLeast(powerhouse, 'Reactor');
     const lines = [];
     lines.push('/**');
     lines.push(' * Per-CLI typed framework binding.');
@@ -22,24 +42,30 @@ export function buildFrameworkTs(spec) {
     }
     lines.push('');
     lines.push('export const configSchema = z.object({');
+    lines.push('  // @clint:begin framework-config');
     if (mastra.enabled) {
-        lines.push("  model: z.string().default('anthropic/claude-haiku-4-5').describe('LLM model to use'),");
+        const defaultModel = mastra.models.find(m => m.isDefault)?.id ?? 'anthropic/claude-sonnet-4-5';
+        lines.push(`  model: z.string().default('${defaultModel}').describe('LLM model to use'),`, `  agentLogging: z.boolean().default(false).describe('Enable agent conversation logging'),`);
     }
-    // Ports are derived from CLI name by resolveReactorDefaults() — no config fields needed.
-    // Override via switchboard.port / connect.port in configureReactor() if required.
-    lines.push('  // Add your own config fields here — this file survives regens.');
+    lines.push('  // @clint:end framework-config');
     lines.push('});');
     lines.push('');
     lines.push('export const secretsSchema = z.object({');
+    lines.push('  // @clint:begin framework-secrets');
     if (mastra.enabled) {
-        lines.push("  apiKey: z.string().optional().describe('LLM API key'),");
+        const providers = [...new Set(mastra.models.map(m => m.id.split(/[:/]/)[0]))];
+        for (const provider of providers) {
+            const field = `${provider}ApiKey`;
+            lines.push(`  ${field}: z.string().optional().describe('${provider} API key'),`);
+        }
     }
+    lines.push('  // @clint:end framework-secrets');
     lines.push('});');
     lines.push('');
     lines.push('export type Config = z.infer<typeof configSchema> &');
     lines.push('  z.infer<typeof secretsSchema>;');
     lines.push('');
-    lines.push('const fullConfigSchema = configSchema.merge(secretsSchema);');
+    lines.push('const fullConfigSchema = configSchema.extend(secretsSchema.shape);');
     lines.push('');
     if (hasGen) {
         lines.push('export const {');

package/dist/codegen/builders/index.d.ts

@@ -1,44 +1 @@
-/**
- * Registry of file builders. Each entry knows its own relative path (within
- * the CLI sub-tree) and a function that builds its content from the spec.
- *
- * Orchestrated by `codegen/index.ts` — it walks this registry, adjusts paths
- * for flat vs split layouts, and writes the files.
- */
-import { buildCliPackageJson } from './cli-package-json.js';
-import { buildCliTs } from './cli-ts.js';
-import { buildConfigTs } from './config-ts.js';
-import { buildMainTs } from './main-ts.js';
-import { buildTsconfigJson } from './tsconfig-json.js';
-import { buildJestConfigJs } from './jest-config-js.js';
-import { buildEslintConfigJs } from './eslint-config-js.js';
-import { buildGitignore } from './gitignore.js';
-import { buildMastraIndexTs } from './mastra-index-ts.js';
-import { buildBuildSkillsScript } from './build-skills-ts.js';
-import { buildAgentBaseMd } from './agent-base-md.js';
-import { buildAgentTs } from './agent-ts.js';
-import { buildFrameworkGenTs } from './framework-gen-ts.js';
-import { buildFrameworkTs } from './framework-ts.js';
-import { type ClintProjectSpec } from '../../spec/types.js';
-/**
- * A spec-driven file builder. Returns `null` from `build` to indicate the
- * file should not be emitted for the given spec.
- */
-export interface FileBuilder {
-    /** Path relative to the CLI root (flat or `{name}-cli/`). */
-    relativePath: string;
-    build(spec: ClintProjectSpec): string | null;
-    /**
-     * When true, this file is only emitted on `mode: 'create'`. In `update`
-     * mode the planner ignores the builder entirely, leaving any on-disk
-     * version untouched regardless of hash state. Used for files that carry
-     * user-owned hand edits (e.g. `src/framework.ts`'s `configSchema`).
-     */
-    initOnly?: boolean;
-}
-export declare const CLI_FILE_BUILDERS: FileBuilder[];
-export { buildCliPackageJson, buildCliTs, buildConfigTs, buildMainTs, buildTsconfigJson, buildJestConfigJs, buildEslintConfigJs, buildGitignore, buildMastraIndexTs, buildBuildSkillsScript, buildAgentBaseMd, buildAgentTs, buildFrameworkGenTs, buildFrameworkTs, };
-export { buildRootPackageJson } from './root-package-json.js';
-export { buildPublishConfigTs } from './publish-config-ts.js';
-export { buildReadme } from './readme-md.js';
-export { buildAppIndexTs } from './app-index-ts.js';
+export { type FileBuilder, CLI_FILE_BUILDERS, getProfileFileBuilders, buildCliPackageJson, buildCliTs, buildConfigTs, buildMainTs, buildTsconfigJson, buildJestConfigJs, buildEslintConfigJs, buildGitignore, buildMastraIndexTs, buildBuildSkillsScript, buildAgentBaseMd, buildAgentTs, buildDemoAgentTs, buildFrameworkGenTs, buildFrameworkTs, buildManifestJson, buildSmokeTestTs, buildRootPackageJson, buildPublishConfigJs, buildReadme, buildAppIndexTs, } from '@powerhousedao/ph-clint-dev/codegen/builders';

package/dist/codegen/builders/index.js

@@ -1,61 +1 @@
-/**
- * Registry of file builders. Each entry knows its own relative path (within
- * the CLI sub-tree) and a function that builds its content from the spec.
- *
- * Orchestrated by `codegen/index.ts` — it walks this registry, adjusts paths
- * for flat vs split layouts, and writes the files.
- */
-import { buildCliPackageJson } from './cli-package-json.js';
-import { buildCliTs } from './cli-ts.js';
-import { buildConfigTs } from './config-ts.js';
-import { buildMainTs } from './main-ts.js';
-import { buildTsconfigJson } from './tsconfig-json.js';
-import { buildJestConfigJs } from './jest-config-js.js';
-import { buildEslintConfigJs } from './eslint-config-js.js';
-import { buildGitignore } from './gitignore.js';
-import { buildMastraIndexTs } from './mastra-index-ts.js';
-import { buildBuildSkillsScript } from './build-skills-ts.js';
-import { buildAgentBaseMd } from './agent-base-md.js';
-import { buildAgentTs } from './agent-ts.js';
-import { buildFrameworkGenTs } from './framework-gen-ts.js';
-import { buildFrameworkTs } from './framework-ts.js';
-export const CLI_FILE_BUILDERS = [
-    { relativePath: 'package.json', build: buildCliPackageJson },
-    { relativePath: 'tsconfig.json', build: () => buildTsconfigJson() },
-    { relativePath: 'jest.config.js', build: () => buildJestConfigJs() },
-    { relativePath: 'eslint.config.js', build: () => buildEslintConfigJs() },
-    { relativePath: '.gitignore', build: () => buildGitignore() },
-    { relativePath: 'src/main.ts', build: () => buildMainTs() },
-    { relativePath: 'src/cli.ts', build: buildCliTs },
-    { relativePath: 'src/config.ts', build: buildConfigTs },
-    // User-owned; init-only. Holds `configSchema` + `secretsSchema` edits.
-    { relativePath: 'src/framework.ts', build: buildFrameworkTs, initOnly: true },
-    // Machine-owned; regenerated on every run. Null when no document types.
-    { relativePath: 'src/framework.gen.ts', build: buildFrameworkGenTs },
-    { relativePath: 'src/mastra/index.ts', build: buildMastraIndexTs },
-    { relativePath: 'scripts/build-skills.ts', build: () => buildBuildSkillsScript() },
-    { relativePath: 'prompts/agent-profiles/AgentBase.md', build: buildAgentBaseMd },
-    {
-        relativePath: 'src/agents/agent.ts',
-        build: (spec) => (spec.features.mastra.enabled ? buildAgentTs(spec) : null),
-    },
-    // Gitkeep placeholders so directories are tracked in git when otherwise empty.
-    { relativePath: 'src/commands/.gitkeep', build: () => '' },
-    { relativePath: 'src/services/.gitkeep', build: () => '' },
-    {
-        relativePath: 'src/triggers/.gitkeep',
-        build: (spec) => (spec.features.routine.enabled ? '' : ''),
-    },
-    {
-        relativePath: 'src/agents/.gitkeep',
-        build: (spec) => (spec.features.mastra.enabled ? null : ''),
-    },
-    { relativePath: 'prompts/skills-tpl/.gitkeep', build: () => '' },
-    { relativePath: 'prompts/skills-ext/.gitkeep', build: () => '' },
-    { relativePath: 'tests/.gitkeep', build: () => '' },
-];
-export { buildCliPackageJson, buildCliTs, buildConfigTs, buildMainTs, buildTsconfigJson, buildJestConfigJs, buildEslintConfigJs, buildGitignore, buildMastraIndexTs, buildBuildSkillsScript, buildAgentBaseMd, buildAgentTs, buildFrameworkGenTs, buildFrameworkTs, };
-export { buildRootPackageJson } from './root-package-json.js';
-export { buildPublishConfigTs } from './publish-config-ts.js';
-export { buildReadme } from './readme-md.js';
-export { buildAppIndexTs } from './app-index-ts.js';
+export { CLI_FILE_BUILDERS, getProfileFileBuilders, buildCliPackageJson, buildCliTs, buildConfigTs, buildMainTs, buildTsconfigJson, buildJestConfigJs, buildEslintConfigJs, buildGitignore, buildMastraIndexTs, buildBuildSkillsScript, buildAgentBaseMd, buildAgentTs, buildDemoAgentTs, buildFrameworkGenTs, buildFrameworkTs, buildManifestJson, buildSmokeTestTs, buildRootPackageJson, buildPublishConfigJs, buildReadme, buildAppIndexTs, } from '@powerhousedao/ph-clint-dev/codegen/builders';

package/dist/codegen/builders/manifest-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Builds `powerhouse.manifest.json` — a machine-readable manifest describing
+ * the CLI project's capabilities for service discovery and deployment.
+ */
+import { type ClintProjectSpec } from '../../spec/types.js';
+export declare function buildManifestJson(spec: ClintProjectSpec): string;

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

@@ -0,0 +1,31 @@
+/**
+ * Builds `powerhouse.manifest.json` — a machine-readable manifest describing
+ * the CLI project's capabilities for service discovery and deployment.
+ */
+import { getBinName, getAppPackageName, phAtLeast, } from '../../spec/types.js';
+export function buildManifestJson(spec) {
+    const { mastra, powerhouse } = spec.features;
+    const agent = mastra.enabled
+        ? {
+            id: mastra.agentId ?? spec.name,
+            name: mastra.agentName ?? spec.name,
+            description: mastra.agentDescription ?? null,
+            image: mastra.agentImage ?? null,
+            models: mastra.models.map((m) => ({ id: m.id, default: m.isDefault })),
+        }
+        : false;
+    const ph = phAtLeast(powerhouse, 'Reactor')
+        ? {
+            support: powerhouse,
+            package: getAppPackageName(spec),
+        }
+        : false;
+    const manifest = {
+        type: 'clint-project',
+        features: { agent, powerhouse: ph },
+        serviceCommand: getBinName(spec),
+        proxyEnabled: spec.deployment.proxyEnabled,
+        supportedResources: spec.deployment.supportedResources,
+    };
+    return JSON.stringify(manifest, null, 2) + '\n';
+}

package/dist/codegen/builders/mastra-index-ts.d.ts

@@ -3,6 +3,9 @@
  *
  * When Mastra is off, emit a no-op placeholder so the directory still exists
  * and `mastra dev` fails predictably rather than importing partial code.
+ *
+ * When Mastra is on with full agent config, bootstrap the CLI and re-export
+ * the configured Mastra Agent via `cli.bootstrap()`.
  */
 import { type ClintProjectSpec } from '../../spec/types.js';
 export declare function buildMastraIndexTs(spec: ClintProjectSpec): string;

package/dist/codegen/builders/mastra-index-ts.js

@@ -1,28 +1,70 @@
+/**
+ * Derive the `{PROVIDER}_API_KEY` env var name from a provider prefix
+ * (e.g. `anthropic` → `ANTHROPIC_API_KEY`).
+ */
+function getApiKeyEnvVar(provider) {
+    return `${provider.toUpperCase()}_API_KEY`;
+}
 export function buildMastraIndexTs(spec) {
     const { mastra } = spec.features;
     if (!mastra.enabled) {
         return [
+            '// @clint:begin mastra-index',
             '/**',
             ' * Mastra Studio entry point — placeholder. Enable the `mastra` feature to',
             ' * populate this file. Until then `mastra:*` scripts are effectively no-ops.',
             ' */',
-            '// @clint:begin mastra-index',
             'export {};',
             '// @clint:end mastra-index',
             '',
         ].join('\n');
     }
-    // When Mastra is enabled but we still emit the demo `AgentProvider` shim
-    // (not a real `@mastra/core` Agent), there is no `mastra` export yet —
-    // `mastra dev` will surface a helpful message once you wire a real Agent.
+    // Full agent config available — emit bootstrap-based Mastra instance
+    if (mastra.agentId && mastra.models.length > 0) {
+        const providers = [...new Set(mastra.models.map(m => m.id.split(/[:/]/)[0]))];
+        const lines = [
+            '// @clint:begin mastra-index',
+            '/**',
+            ' * Mastra Studio entry point for `mastra dev` / `mastra build` / `mastra start`.',
+            ' *',
+            ' * Bootstraps the CLI to get the configured agent, then exports a Mastra',
+            ' * instance for Studio integration.',
+            ' */',
+            "import { Mastra } from '@mastra/core/mastra';",
+            "import type { Agent } from '@mastra/core/agent';",
+            "import path from 'node:path';",
+            "import { cli } from '../cli.js';",
+            "import { CLI_ROOT } from '../config.js';",
+            '',
+            "// Under `mastra dev`, CLI_ROOT points to .mastra/ (bundler output).",
+            '// The actual project root is its parent.',
+            "const projectRoot = path.basename(CLI_ROOT) === '.mastra'",
+            '  ? path.dirname(CLI_ROOT)',
+            '  : CLI_ROOT;',
+            '',
+            'const rt = await cli.bootstrap({ workdir: projectRoot });',
+            '',
+        ];
+        // API key env bridge for Studio
+        lines.push(`// Workaround: Mastra Studio checks process.env for API keys directly.`, `// Bridge the ph-clint resolved keys so Studio's provider detection works.`);
+        for (const provider of providers) {
+            const field = `${provider}ApiKey`;
+            const envVar = getApiKeyEnvVar(provider);
+            lines.push(`{`, `  const key = rt.config.${field} as string | undefined;`, `  if (key && !process.env.${envVar}) process.env.${envVar} = key;`, `}`);
+        }
+        lines.push('');
+        lines.push('const mastraAgent = await rt.mastraAgent as Agent | undefined;', '', 'export const mastra = new Mastra({', '  agents: mastraAgent ? { [mastraAgent.id]: mastraAgent } : {},', '});', '// @clint:end mastra-index', '');
+        return lines.join('\n');
+    }
+    // Mastra enabled but no full agent config yet — placeholder
     return [
+        '// @clint:begin mastra-index',
         '/**',
         ' * Mastra Studio entry point for `mastra dev` / `mastra build` / `mastra start`.',
         ' *',
         " * Re-export a configured `@mastra/core` Mastra instance from here once you",
         " * replace the demo createAgent shim with a real Mastra Agent.",
         ' */',
-        '// @clint:begin mastra-index',
         'export {};',
         '// @clint:end mastra-index',
         '',

package/dist/codegen/builders/publish-config-js.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Builds the root `publish.config.js`.
+ *
+ * Split-layout: a lockstep group with both app and cli packages.
+ * Single-layout: a single-package group at `.`.
+ */
+import { type ClintProjectSpec } from '../../spec/types.js';
+export declare function buildPublishConfigJs(spec: ClintProjectSpec): string;

package/dist/codegen/builders/publish-config-js.js

@@ -0,0 +1,33 @@
+/**
+ * Builds the root `publish.config.js`.
+ *
+ * Split-layout: a lockstep group with both app and cli packages.
+ * Single-layout: a single-package group at `.`.
+ */
+import { phAtLeast, getBinName, getAppFolderName, getCliFolderName, } from '../../spec/types.js';
+export function buildPublishConfigJs(spec) {
+    const split = phAtLeast(spec.features.powerhouse, 'Reactor');
+    // The publish pipeline appends the prerelease suffix (e.g. -dev.0), so we
+    // only store the base semver (M.m.p) here.
+    const baseVersion = spec.version.replace(/-.*$/, '');
+    const binName = getBinName(spec);
+    const packages = split
+        ? `[
+        { path: '${getAppFolderName(spec)}', category: 'app' },
+        { path: '${getCliFolderName(spec)}', category: 'cli' },
+      ]`
+        : `[
+        { path: '.', category: 'cli' },
+      ]`;
+    return `// Publish config — loaded by ph-clint's publish pipeline.
+// definePublishConfig is an identity function; a plain export is equivalent.
+export default {
+  groups: {
+    '${binName}': {
+      version: '${baseVersion}',
+      packages: ${packages},
+    },
+  },
+};
+`;
+}

package/dist/codegen/builders/publish-config-ts.d.ts

@@ -1,6 +1,8 @@
 /**
- * Builds the root `publish.config.ts` for split-layout projects.
- * Defines a single lockstep group containing both the app and cli packages.
+ * Builds the root `publish.config.ts`.
+ *
+ * Split-layout: a lockstep group with both app and cli packages.
+ * Single-layout: a single-package group at `.`.
  */
 import { type ClintProjectSpec } from '../../spec/types.js';
 export declare function buildPublishConfigTs(spec: ClintProjectSpec): string;