@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/create/cwdJail.test.ts

@@ -13,7 +13,7 @@
  * ambient process directory.
  */
 
-import { existsSync, mkdtempSync, readdirSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, symlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -58,23 +58,42 @@ describe("create cwd/jail atomicity (PROTECTED)", () => {
     expect(readdirSync(serverDir)).toEqual([]);
   });
 
-  it("rejects an escape past the per-call cwd — validated against the SAME cwd", async () => {
+  it("rejects a symlink escape past the per-call cwd — the JAIL validates against the SAME cwd", async () => {
     const serverDir = freshDir("server");
     const projA = freshDir("projA");
     const escapeSibling = freshDir("escape");
+    // A symlink INSIDE the jailed dir pointing out of it: the one escape
+    // class the shared prompt validator (cwd-agnostic, value-only) passes,
+    // so only the jail — resolving the path against the INJECTED cwd — can
+    // refuse it. A `..`/absolute vector would be consumed by the validator
+    // one gate earlier and prove nothing about which root the jail reads.
+    symlinkSync(escapeSibling, join(projA, "link"));
     const mcp = await projectMcp([createModule], serverDir);
     cleanup = mcp.cleanup;
 
     const result = await mcp.callTool("create_component", {
       ...COMPONENT_ARGS,
-      componentPath: "../escape/Bad",
+      componentPath: "link/Bad",
       cwd: projA,
       confirm: true,
     });
 
     expect(result.ok).toBe(false);
-    expect((result.error as { code: string }).code).toBe("INVALID_INPUT");
-    // Nothing was written into the sibling the path tried to escape into.
+    const error = result.error as {
+      code: string;
+      message: string;
+      recovery?: { message: string };
+    };
+    expect(error.code).toBe("INVALID_INPUT");
+    // The jail's OWN tier answered: its spelling and its covenant recovery
+    // field — were the jail handed the ambient process cwd instead of the
+    // injected one, `link` would not resolve there and the run would write
+    // into the sibling.
+    expect(error.message).toBe('Invalid componentPath "link/Bad".');
+    expect(error.recovery?.message).toBe(
+      "The path resolves outside the workspace.",
+    );
+    // Nothing was written into the sibling the symlink pointed at.
     expect(readdirSync(escapeSibling)).toEqual([]);
   });
 

package/src/capabilities/create/generatorToVerbSpec.test.ts

@@ -0,0 +1,186 @@
+/**
+ * The prompt→param adapter, pinned cell by cell with LITERAL expectations —
+ * the direct coverage the replaced adapter-parity describe dropped. The
+ * projection-fidelity test holds `CREATE_SURFACE` to the live generators;
+ * `create.verb.ts` builds its params FROM this adapter — so the adapter
+ * itself must be pinned against literals, not against its own output.
+ * Includes the appPath `my-app` default the MCP schema serves.
+ */
+
+import { describe, expect, it } from "vitest";
+import { createVerbs } from "./create.verb.js";
+import { CREATE_SURFACE } from "./createSurface.generated.js";
+import {
+  declarativeDoc,
+  generatorToParams,
+  promptToParam,
+} from "./generatorToVerbSpec.js";
+
+describe("declarativeDoc — wizard question to help sentence", () => {
+  it("strips the trailing ?/: and ends with a period", () => {
+    expect(declarativeDoc("Include styles?")).toBe("Include styles.");
+    expect(declarativeDoc("Package name:")).toBe("Package name.");
+  });
+
+  it("keeps an existing terminal, and passes empty through", () => {
+    expect(declarativeDoc("Already a sentence.")).toBe("Already a sentence.");
+    expect(declarativeDoc("Watch out!")).toBe("Watch out!");
+    expect(declarativeDoc("  ")).toBe("");
+  });
+});
+
+describe("promptToParam — the type × default × positional × conditional matrix", () => {
+  it("text + default + positional + path-name → optional positional string with files completion", () => {
+    expect(
+      promptToParam({
+        name: "appPath",
+        type: "text",
+        message: "Application directory name:",
+        default: "my-app",
+        positional: true,
+      }),
+    ).toEqual({
+      kind: "string",
+      name: "appPath",
+      doc: "Application directory name.",
+      required: false,
+      positional: true,
+      default: "my-app",
+      complete: { kind: "files" },
+    });
+  });
+
+  it("text without default or condition → required flag string, no completion", () => {
+    expect(
+      promptToParam({ name: "title", type: "text", message: "Title:" }),
+    ).toEqual({
+      kind: "string",
+      name: "title",
+      doc: "Title.",
+      required: true,
+      positional: false,
+    });
+  });
+
+  it("a conditional prompt is never required — projected and live `when` alike", () => {
+    expect(
+      promptToParam({
+        name: "useTsStories",
+        type: "confirm",
+        message: "Use TS stories?",
+        conditional: true,
+      }).required,
+    ).toBe(false);
+    expect(
+      promptToParam({
+        name: "useTsStories",
+        type: "confirm",
+        message: "Use TS stories?",
+        when: () => true,
+      }).required,
+    ).toBe(false);
+  });
+
+  it("confirm carries its boolean default in both polarities", () => {
+    expect(
+      promptToParam({
+        name: "withStyles",
+        type: "confirm",
+        message: "Include styles?",
+        default: true,
+      }),
+    ).toEqual({
+      kind: "boolean",
+      name: "withStyles",
+      doc: "Include styles.",
+      required: false,
+      positional: false,
+      default: true,
+    });
+    expect(
+      promptToParam({
+        name: "relay",
+        type: "confirm",
+        message: "Include Relay?",
+        default: false,
+      }),
+    ).toMatchObject({ kind: "boolean", default: false });
+  });
+
+  it("select → enum over the choice values, default stringified", () => {
+    expect(
+      promptToParam({
+        name: "type",
+        type: "select",
+        message: "Package type:",
+        choices: [
+          { label: "Tool", value: "tool-ts" },
+          { label: "Library", value: "library" },
+        ],
+        default: "tool-ts",
+      }),
+    ).toEqual({
+      kind: "enum",
+      name: "type",
+      doc: "Package type.",
+      values: ["tool-ts", "library"],
+      required: false,
+      positional: false,
+      default: "tool-ts",
+    });
+  });
+
+  it("multiselect → string[] with values completion and NO default slot", () => {
+    const param = promptToParam({
+      name: "features",
+      type: "multiselect",
+      message: "Features:",
+      choices: [{ label: "X", value: "x" }],
+      default: ["x"],
+    });
+    expect(param).toEqual({
+      kind: "string[]",
+      name: "features",
+      doc: "Features.",
+      required: false,
+      positional: false,
+      complete: { kind: "values" },
+    });
+    expect("default" in param).toBe(false);
+  });
+});
+
+describe("generatorToParams — order and the live appPath default", () => {
+  it("maps in declared prompt order", () => {
+    const params = generatorToParams([
+      { name: "b", type: "text", message: "B:" },
+      { name: "a", type: "text", message: "A:" },
+    ]);
+    expect(params.map((param) => param.name)).toEqual(["b", "a"]);
+  });
+
+  it("the live create_application schema carries appPath default my-app (LITERAL)", () => {
+    // End-to-end through the committed surface: the generator's positional
+    // prompt default must survive into the binding param the MCP schema and
+    // reference serve. A literal, so promptToParam dropping `default` for
+    // positional prompts goes red here even while surface fidelity is green.
+    const appPath = createVerbs.application.params.find(
+      (param) => param.name === "appPath",
+    );
+    expect(appPath).toEqual({
+      kind: "string",
+      name: "appPath",
+      doc: "Application directory name.",
+      required: false,
+      positional: true,
+      default: "my-app",
+      complete: { kind: "files" },
+    });
+    // The projected surface it derives from says the same thing.
+    expect(
+      CREATE_SURFACE["application/react"]?.prompts.find(
+        (prompt) => prompt.name === "appPath",
+      )?.default,
+    ).toBe("my-app");
+  });
+});

package/src/capabilities/create/generatorToVerbSpec.ts

@@ -15,14 +15,17 @@
  * input a wizard would. A `when` condition is honoured by `collectAnswers` at
  * prompt time. `generate` is reached through the verb's `run` → `execute`.
  *
- * This adapter runs over STATIC prompt mirrors (see `create.verb.ts`), never the
- * live generators — importing a generator runs a top-level `await loadTemplate`,
- * which must stay behind `create`'s lazy dispatch (R9). A parity test loads the
- * real generators and asserts the mirrors match.
+ * This adapter runs over the build-time PROJECTION of the generators'
+ * prompts (`createSurface.generated.ts`), never the live generators —
+ * importing a generator pulls summon-core, which must stay behind `create`'s
+ * lazy dispatch (R9). The projection-fidelity test loads the real generators
+ * and asserts the committed projection matches. It accepts a live
+ * `PromptDefinition` equally (the shapes are compatible): a projected
+ * prompt's `when` survives as `conditional: true`.
  */
 
-import type { PromptDefinition } from "@canonical/summon-core";
-import type { ParamSpec } from "../../kernel/spec/types.js";
+import type { PromptLike } from "@canonical/summon-core/projection";
+import type { ParamSpec } from "../../kernel/spec/index.js";
 
 /** A path-like text prompt gets file completion. */
 const looksLikePath = (name: string): boolean => /(path|dir)$/i.test(name);
@@ -53,8 +56,9 @@ export function declarativeDoc(message: string): string {
  * @param prompt - The generator's prompt definition.
  * @returns The equivalent {@link ParamSpec}.
  */
-export function promptToParam(prompt: PromptDefinition): ParamSpec {
-  const required = prompt.default === undefined && !prompt.when;
+export function promptToParam(prompt: PromptLike): ParamSpec {
+  const required =
+    prompt.default === undefined && !prompt.when && prompt.conditional !== true;
   const positional = prompt.positional === true;
 
   switch (prompt.type) {
@@ -104,8 +108,6 @@ export function promptToParam(prompt: PromptDefinition): ParamSpec {
 }
 
 /** Map a generator's whole prompt list to grammar params, in order. */
-export function generatorToParams(
-  prompts: readonly PromptDefinition[],
-): ParamSpec[] {
+export function generatorToParams(prompts: readonly PromptLike[]): ParamSpec[] {
   return prompts.map(promptToParam);
 }

package/src/capabilities/create/index.ts

@@ -1,17 +1,20 @@
 /**
  * The `create` capability barrel — component / package / application scaffolds.
  *
- * Importing this pulls only the verb specs (static params + formatters); every
- * generator load and the summon-core runtime stay behind each verb's lazy
- * `run` dispatch, so the command tree builds without touching summon-core.
+ * Importing this pulls only the verb specs (params derived from the committed
+ * projection), the mount, and the formatters; every generator load and the
+ * summon-core runtime stay behind the lazy `run` dispatch, so the command
+ * tree builds without touching summon-core.
  */
 
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
+import { createCliProjection } from "./cliProjection.js";
 import { createVerbs } from "./create.verb.js";
 
 /** The `create` capability module. */
 export const createModule: CapabilityModule = {
   name: "create",
   verbs: Object.values(createVerbs).map(asVerb),
+  cliProjection: createCliProjection(),
 };

package/src/capabilities/create/messages.ts

@@ -0,0 +1,18 @@
+/**
+ * Authored messages of the `create` surface that the BIN needs on its parse
+ * error path — imported (lazily) by `handleProgramError`, authored here so
+ * the kernel carries no create-domain literal.
+ */
+
+import { BIN_NAME } from "../../constants.js";
+import { COMPONENT_FRAMEWORKS } from "./constants.js";
+
+/**
+ * The R1 death of the old grammar: `--framework` is not a flag any more, and
+ * a parse failure whose argv still carries it gets THIS message (exit 2),
+ * naming the new form — no shim, no silent rebinding.
+ */
+export const FRAMEWORK_FLAG_ERROR =
+  "error: unknown option '--framework' — the framework is now a path segment: " +
+  `\`${BIN_NAME} create component <${COMPONENT_FRAMEWORKS.join("|")}> [component-path]\` ` +
+  "(create mirrors summon).";