refactor(create-plugin): move app-sdk addition off direct output

Author: sunker

packages/create-plugin/src/codemods/additions/scripts/experimental-app-sdk.test.ts

@@ -1,5 +1,4 @@
 import { Context } from '../../context.js';
-import { output } from '../../../utils/utils.console.js';
 import appSdk from './experimental-app-sdk.js';
 
 vi.mock(import('../../../utils/utils.plugin.js'), async (importOriginal) => {
@@ -10,15 +9,11 @@ vi.mock(import('../../../utils/utils.plugin.js'), async (importOriginal) => {
   };
 });
 
-
 vi.mock(import('../../utils.js'), async (importOriginal) => {
   const originalModule = await importOriginal();
   // Disk I/O is slow so render the templates once and key off the requested path.
   const render = (file: string) =>
-    originalModule.renderTemplate(
-      new URL(`../../../../templates/app-sdk/${file}`, import.meta.url).pathname,
-      false
-    );
+    originalModule.renderTemplate(new URL(`../../../../templates/app-sdk/${file}`, import.meta.url).pathname, false);
   const rendered: Record<string, string> = {
     '.config/app-sdk/generate-kinds.mjs': render('.config/app-sdk/generate-kinds.mjs'),
     '.config/AGENTS/app-sdk.md': render('.config/AGENTS/app-sdk.md'),
@@ -78,11 +73,7 @@ function createAppContext({
 }
 
 describe('experimental-app-sdk addition', () => {
-  // Silence terminal output, and let us assert on what the user is told.
-  beforeEach(() => {
-    vi.spyOn(output, 'log').mockImplementation(() => {});
-    vi.spyOn(output, 'warning').mockImplementation(() => {});
-  });
+  // no output spies needed - the codemod prints nothing, it records on the context
 
   afterEach(() => {
     vi.restoreAllMocks();
@@ -304,35 +295,44 @@ describe('experimental-app-sdk addition', () => {
     });
   });
 
+  // the codemod records what to say; the command renders it. see Context.addNextStep / Context.skip
   describe('user messaging', () => {
     it('explains why it skipped an unsupported plugin type', () => {
       const context = createAppContext({ pluginType: 'panel' });
 
       appSdk(context);
 
-      expect(output.warning).toHaveBeenCalledWith(
-        expect.objectContaining({ title: expect.stringContaining('needs an app plugin') })
-      );
+      expect(context.getSkip()?.reason).toContain('needs an app plugin');
     });
 
-    it('prints next steps after scaffolding', () => {
+    it('explains a missing plugin.json rather than failing silently', () => {
+      const context = new Context();
+
+      appSdk(context);
+
+      expect(context.getSkip()?.reason).toContain('src/plugin.json');
+      expect(context.getSkip()?.hints).toContain('Run this from the root of your plugin.');
+    });
+
+    it('records next steps after scaffolding', () => {
       const context = createAppContext();
 
       appSdk(context);
 
-      expect(output.log).toHaveBeenCalledWith(expect.objectContaining({ title: expect.stringContaining('Next steps') }));
+      expect(context.getSkip()).toBeUndefined();
+      expect(context.listNextSteps().join('\n')).toContain('generate:kinds');
     });
 
     it('stays quiet on a re-run', () => {
       const context = createAppContext();
       appSdk(context);
-      vi.mocked(output.log).mockClear();
+      const afterFirstRun = context.listNextSteps().length;
 
       appSdk(context);
 
-      expect(output.log).not.toHaveBeenCalled();
+      // nothing was scaffolded the second time, so nothing new to say
+      expect(context.listNextSteps()).toHaveLength(afterFirstRun);
     });
-
   });
 
   it('is idempotent', async () => {

packages/create-plugin/src/codemods/additions/scripts/experimental-app-sdk.ts

@@ -1,7 +1,6 @@
 import { fileURLToPath } from 'node:url';
 import { parseDocument, stringify, YAMLMap, Scalar } from 'yaml';
 import type { Context } from '../../context.js';
-import { output } from '../../../utils/utils.console.js';
 import { additionsDebug, renderTemplate } from '../../utils.js';
 import { getTemplateData } from '../../../utils/utils.templates.js';
 
@@ -43,7 +42,7 @@ export default function appSdk(context: Context): Context {
 
   // Only guide the user when we actually scaffolded something; a re-run should stay quiet.
   if (Object.keys(context.listChanges()).length > changesBefore) {
-    printNextSteps();
+    addNextSteps(context);
   }
 
   return context;
@@ -57,7 +56,7 @@ function isAppPlugin(context: Context): boolean {
   const pluginJsonContent = context.getFile('src/plugin.json');
 
   if (!pluginJsonContent) {
-    skip('Could not find src/plugin.json.', ['Run this from the root of your plugin.']);
+    context.skip('could not find src/plugin.json.', ['Run this from the root of your plugin.']);
     return false;
   }
 
@@ -66,28 +65,23 @@ function isAppPlugin(context: Context): boolean {
     pluginJson = JSON.parse(pluginJsonContent);
   } catch (error) {
     additionsDebug(`Failed to parse src/plugin.json: ${error}`);
-    skip('Could not parse src/plugin.json.');
+    context.skip('could not parse src/plugin.json.');
     return false;
   }
 
   if (pluginJson.type !== 'app') {
-    skip(`grafana-app-sdk codegen needs an app plugin, but this is a ${pluginJson.type} plugin.`, [
-      'The app-sdk serves Kubernetes-style resources from an app plugin.',
-    ]);
+    context.skip(
+      pluginJson.type
+        ? `needs an app plugin, but this is a ${pluginJson.type} plugin.`
+        : 'needs an app plugin, but src/plugin.json declares no type.',
+      ['The app-sdk serves Kubernetes-style resources from an app plugin.']
+    );
     return false;
   }
 
   return true;
 }
 
-/**
- * Explains why nothing happened. The runner reports success for a no-op codemod, so without this the
- * user is left guessing.
- */
-function skip(title: string, body: string[] = []) {
-  output.warning({ title: `Skipping app-sdk: ${title}`, body });
-}
-
 function addTemplateFiles(context: Context) {
   for (const file of TEMPLATE_FILES) {
     if (context.doesFileExist(file)) {
@@ -223,16 +217,11 @@ function addFeatureToggle(context: Context) {
   context.updateFile(composePath, stringify(composeData, { lineWidth: 120, singleQuote: true }));
 }
 
-/** Tells the user what to run next. */
-function printNextSteps() {
+/** Records what to run next. The command renders these once the changes are on disk. */
+function addNextSteps(context: Context) {
   const { packageManagerName } = getTemplateData();
 
-  output.log({
-    title: 'Added grafana-app-sdk code generation. Next steps:',
-    body: [
-      'Edit your kinds in ./kinds (start with kinds/example.cue), then run:',
-      `  ${packageManagerName} run generate:kinds`,
-      'See ./kinds/README.md for the full workflow.',
-    ],
-  });
+  context.addNextStep('Edit your kinds in ./kinds, starting with kinds/example.cue');
+  context.addNextStep(`Run \`${packageManagerName} run generate:kinds\` to generate from them`);
+  context.addNextStep('See ./kinds/README.md for the full workflow');
 }