@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/create/createHelp.ts

@@ -0,0 +1,71 @@
+/**
+ * Pragma's presentation of a `create` leaf's grouped help — the host half of
+ * the summon-core help seam (`CommanderHost.renderHelp`): the projection
+ * decides the STRUCTURE (usage, description, the option groups, the host's
+ * flag rows), this module effects pragma's house style over it, composed from
+ * the same kernel primitives every other help page uses
+ * (`kernel/project/cli/helpFormat.ts`) — a dim `Usage:` label, bold headings,
+ * cyan-term/dim-description columns. Colour therefore rides the kernel's one
+ * gate (chalk's TTY detection plus the style seam's `NO_COLOR` zeroing), so
+ * piped output — the cross-CLI structural-parity surface — stays plain bytes.
+ */
+
+import type { renderGroupedHelp } from "@canonical/summon-core/projection";
+import {
+  helpColumns,
+  helpHeading,
+  helpUsage,
+} from "../../kernel/project/cli/helpFormat.js";
+
+/** One heading + its `[term, description]` rows. */
+type HelpSection = readonly [
+  heading: string,
+  rows: readonly (readonly [term: string, description: string])[],
+];
+
+/**
+ * A row's description with the shared renderer's default-value suffix — the
+ * same bytes `renderGroupedHelp` appends, so the structural-parity cells
+ * compare the fact, not two spellings of it.
+ */
+function describeOption(description: string, defaultValue?: string): string {
+  return defaultValue
+    ? `${description} (default: ${JSON.stringify(defaultValue)})`
+    : description;
+}
+
+/** Render a `create` leaf's grouped help in pragma's house style. */
+export const renderCreateHelp: typeof renderGroupedHelp = (
+  usage,
+  description,
+  groups,
+  hostFlags,
+) => {
+  const sections: HelpSection[] = [
+    ["Global Options", hostFlags.map((flag) => [flag.flags, flag.description])],
+    ...[...groups].map(
+      ([groupName, options]): HelpSection => [
+        groupName,
+        options.map((opt) => [
+          opt.flags,
+          describeOption(opt.description, opt.defaultValue),
+        ]),
+      ],
+    ),
+  ];
+
+  // One column width across ALL sections so the flag column aligns section to
+  // section (the root help does the same for its noun column).
+  const width = Math.max(
+    ...sections.flatMap(([, rows]) => rows.map(([term]) => term.length)),
+    0,
+  );
+
+  const lines: string[] = [helpUsage(usage)];
+  if (description) lines.push("", description);
+  for (const [heading, rows] of sections) {
+    lines.push("", helpHeading(heading), ...helpColumns(rows, width));
+  }
+  // Commander prints `formatHelp`'s return verbatim — terminate the page.
+  return `${lines.join("\n")}\n`;
+};

package/src/capabilities/create/createSurface.generated.ts

@@ -0,0 +1,400 @@
+// AUTO-GENERATED by scripts/build.ts — do not edit by hand.
+// Regenerate: `bun run scripts/build.ts`. The serializable projection of
+// every declared generator binding (`projectGenerator` over the live
+// generators, captured at build time): the create surface's params, the CLI
+// mount, completion, and the MCP schemas all derive from THIS data, so the
+// `--help`/`__complete` fast path never imports a generator. The
+// projection-fidelity test in create.test.ts loads the LIVE generators and
+// fails when this file drifts; rerunning the build fixes it.
+
+import type { SurfaceCommand } from "@canonical/summon-core/projection";
+import type { PromptCliSyntax } from "./types.js";
+
+/** Declared command path → its projected command surface. */
+export const CREATE_SURFACE: Readonly<Record<string, SurfaceCommand>> = {
+  "application/react": {
+    "path": [
+      "application",
+      "react"
+    ],
+    "description": "Scaffold a complete React application with SSR and routing",
+    "prompts": [
+      {
+        "name": "appPath",
+        "type": "text",
+        "message": "Application directory name:",
+        "default": "my-app",
+        "positional": true,
+        "group": "Application"
+      },
+      {
+        "name": "forms",
+        "type": "confirm",
+        "message": "Include form components?",
+        "default": true,
+        "group": "Application"
+      },
+      {
+        "name": "intl",
+        "type": "confirm",
+        "message": "Include internationalisation (locale negotiation, translated UI, locale switcher)?",
+        "default": false,
+        "group": "Application"
+      },
+      {
+        "name": "relay",
+        "type": "confirm",
+        "message": "Include a Relay (GraphQL) data layer with a local mock schema?",
+        "default": false,
+        "group": "Application"
+      },
+      {
+        "name": "runInstall",
+        "type": "confirm",
+        "message": "Install dependencies now?",
+        "default": true,
+        "group": "Application"
+      }
+    ]
+  },
+  "component/lit": {
+    "path": [
+      "component",
+      "lit"
+    ],
+    "description": "Generate a Lit web component with TypeScript, tests, stories, and styles",
+    "prompts": [
+      {
+        "name": "componentPath",
+        "type": "text",
+        "message": "Component path:",
+        "default": "src/lib/components/MyComponent",
+        "positional": true,
+        "group": "Component"
+      },
+      {
+        "name": "withStyles",
+        "type": "confirm",
+        "message": "Include styles?",
+        "default": true,
+        "group": "Options"
+      },
+      {
+        "name": "withStories",
+        "type": "confirm",
+        "message": "Include Storybook stories?",
+        "default": true,
+        "group": "Options"
+      }
+    ]
+  },
+  "component/react": {
+    "path": [
+      "component",
+      "react"
+    ],
+    "description": "Generate a React component with TypeScript, tests, stories, and styles",
+    "prompts": [
+      {
+        "name": "componentPath",
+        "type": "text",
+        "message": "Component path:",
+        "default": "src/components/MyComponent",
+        "positional": true,
+        "group": "Component"
+      },
+      {
+        "name": "withStyles",
+        "type": "confirm",
+        "message": "Include styles?",
+        "default": true,
+        "group": "Options"
+      },
+      {
+        "name": "withStories",
+        "type": "confirm",
+        "message": "Include Storybook stories?",
+        "default": true,
+        "group": "Options"
+      },
+      {
+        "name": "withSsrTests",
+        "type": "confirm",
+        "message": "Include SSR tests?",
+        "default": true,
+        "group": "Options"
+      }
+    ]
+  },
+  "component/svelte": {
+    "path": [
+      "component",
+      "svelte"
+    ],
+    "description": "Generate a Svelte 5 component with TypeScript, tests, stories, and styles",
+    "prompts": [
+      {
+        "name": "componentPath",
+        "type": "text",
+        "message": "Component path:",
+        "default": "src/lib/components/MyComponent",
+        "positional": true,
+        "group": "Component"
+      },
+      {
+        "name": "withStyles",
+        "type": "confirm",
+        "message": "Include styles?",
+        "default": true,
+        "group": "Options"
+      },
+      {
+        "name": "withStories",
+        "type": "confirm",
+        "message": "Include Storybook stories?",
+        "default": true,
+        "group": "Options"
+      },
+      {
+        "name": "withSsrTests",
+        "type": "confirm",
+        "message": "Include SSR tests?",
+        "default": true,
+        "group": "Options"
+      },
+      {
+        "name": "useTsStories",
+        "type": "confirm",
+        "message": "Use TypeScript stories format? (otherwise Svelte CSF)",
+        "default": false,
+        "group": "Options",
+        "conditional": true
+      }
+    ]
+  },
+  "package": {
+    "path": [
+      "package"
+    ],
+    "description": "Generate a new npm package with proper configuration for the pragma monorepo",
+    "prompts": [
+      {
+        "name": "name",
+        "type": "text",
+        "message": "Package name:",
+        "default": "@canonical/my-package",
+        "group": "Package"
+      },
+      {
+        "name": "type",
+        "type": "select",
+        "message": "Package type:",
+        "default": "tool-ts",
+        "choices": [
+          {
+            "label": "tool-ts - TypeScript tool (runs from src/, no build)",
+            "value": "tool-ts"
+          },
+          {
+            "label": "library - Publishable library (dist/ build output)",
+            "value": "library"
+          },
+          {
+            "label": "css - CSS package (src/index.css, no build)",
+            "value": "css"
+          }
+        ],
+        "group": "Package"
+      },
+      {
+        "name": "description",
+        "type": "text",
+        "message": "Package description:",
+        "default": "",
+        "group": "Package"
+      },
+      {
+        "name": "withReact",
+        "type": "confirm",
+        "message": "Include React dependencies?",
+        "default": false,
+        "group": "Options"
+      },
+      {
+        "name": "withStorybook",
+        "type": "confirm",
+        "message": "Include Storybook setup?",
+        "default": false,
+        "group": "Options"
+      },
+      {
+        "name": "withCli",
+        "type": "confirm",
+        "message": "Include CLI binary entry point?",
+        "default": false,
+        "group": "Options"
+      },
+      {
+        "name": "withPrTemplate",
+        "type": "confirm",
+        "message": "Include a .github/PULL_REQUEST_TEMPLATE.md?",
+        "default": false,
+        "group": "Options"
+      },
+      {
+        "name": "runInstall",
+        "type": "confirm",
+        "message": "Run package manager install after creation?",
+        "default": true,
+        "group": "Post-setup"
+      }
+    ]
+  },
+};
+
+/**
+ * Declared command path → prompt name → the REGISTERED CLI spelling
+ * (`buildOptionInfo`/`toKebabCase` over the projected prompts, captured at
+ * build time). Completion and the reference emitter read THIS record, so the
+ * `--help`/`__complete` fast paths never import the registration machinery
+ * to learn a token it already decided.
+ */
+export const CREATE_CLI_SYNTAX: Readonly<
+  Record<string, Readonly<Record<string, PromptCliSyntax>>>
+> = {
+  "application/react": {
+    "appPath": {
+      "flag": "--app-path",
+      "takesValue": true,
+      "kebabName": "app-path"
+    },
+    "forms": {
+      "flag": "--no-forms",
+      "takesValue": false,
+      "kebabName": "forms"
+    },
+    "intl": {
+      "flag": "--intl",
+      "takesValue": false,
+      "kebabName": "intl"
+    },
+    "relay": {
+      "flag": "--relay",
+      "takesValue": false,
+      "kebabName": "relay"
+    },
+    "runInstall": {
+      "flag": "--no-run-install",
+      "takesValue": false,
+      "kebabName": "run-install"
+    }
+  },
+  "component/lit": {
+    "componentPath": {
+      "flag": "--component-path",
+      "takesValue": true,
+      "kebabName": "component-path"
+    },
+    "withStyles": {
+      "flag": "--no-with-styles",
+      "takesValue": false,
+      "kebabName": "with-styles"
+    },
+    "withStories": {
+      "flag": "--no-with-stories",
+      "takesValue": false,
+      "kebabName": "with-stories"
+    }
+  },
+  "component/react": {
+    "componentPath": {
+      "flag": "--component-path",
+      "takesValue": true,
+      "kebabName": "component-path"
+    },
+    "withStyles": {
+      "flag": "--no-with-styles",
+      "takesValue": false,
+      "kebabName": "with-styles"
+    },
+    "withStories": {
+      "flag": "--no-with-stories",
+      "takesValue": false,
+      "kebabName": "with-stories"
+    },
+    "withSsrTests": {
+      "flag": "--no-with-ssr-tests",
+      "takesValue": false,
+      "kebabName": "with-ssr-tests"
+    }
+  },
+  "component/svelte": {
+    "componentPath": {
+      "flag": "--component-path",
+      "takesValue": true,
+      "kebabName": "component-path"
+    },
+    "withStyles": {
+      "flag": "--no-with-styles",
+      "takesValue": false,
+      "kebabName": "with-styles"
+    },
+    "withStories": {
+      "flag": "--no-with-stories",
+      "takesValue": false,
+      "kebabName": "with-stories"
+    },
+    "withSsrTests": {
+      "flag": "--no-with-ssr-tests",
+      "takesValue": false,
+      "kebabName": "with-ssr-tests"
+    },
+    "useTsStories": {
+      "flag": "--use-ts-stories",
+      "takesValue": false,
+      "kebabName": "use-ts-stories"
+    }
+  },
+  "package": {
+    "name": {
+      "flag": "--name",
+      "takesValue": true,
+      "kebabName": "name"
+    },
+    "type": {
+      "flag": "--type",
+      "takesValue": true,
+      "kebabName": "type"
+    },
+    "description": {
+      "flag": "--description",
+      "takesValue": true,
+      "kebabName": "description"
+    },
+    "withReact": {
+      "flag": "--with-react",
+      "takesValue": false,
+      "kebabName": "with-react"
+    },
+    "withStorybook": {
+      "flag": "--with-storybook",
+      "takesValue": false,
+      "kebabName": "with-storybook"
+    },
+    "withCli": {
+      "flag": "--with-cli",
+      "takesValue": false,
+      "kebabName": "with-cli"
+    },
+    "withPrTemplate": {
+      "flag": "--with-pr-template",
+      "takesValue": false,
+      "kebabName": "with-pr-template"
+    },
+    "runInstall": {
+      "flag": "--no-run-install",
+      "takesValue": false,
+      "kebabName": "run-install"
+    }
+  },
+};