swallowkit 2.0.0-alpha.3 → 2.0.0-alpha.4

package/src/__tests__/schema-analysis.test.ts

@@ -0,0 +1,329 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { parseModelFile } from "../core/scaffold/model-parser";
+import { generateOpenApiDocument } from "../core/scaffold/openapi-generator";
+import { generateListPage, generateFormComponent } from "../core/scaffold/ui-generator";
+import { generateLanguageSchemaArtifacts, getPythonRegexWarnings, toPythonRegex } from "../core/scaffold/native-schema-generator";
+import { generateDetailPage } from "../core/scaffold/ui-generator";
+import { spawnSync } from "child_process";
+import { FileOperationSession } from "../core/operations/file-session";
+import { buildUserScopedDataWarning } from "../cli/commands/scaffold";
+import { inspectCapabilities } from "../core/project/capabilities";
+
+const repoRoot = path.resolve(__dirname, "..", "..");
+
+function model(name: string, fields: string, extra = ""): string {
+  const pascal = name.replace(/(^|-)([a-z])/g, (_, __, char: string) => char.toUpperCase());
+  return `import { z } from 'zod/v4';
+export const ${pascal} = z.object({
+  id: z.string(),
+${fields}
+});
+export type ${pascal} = z.infer<typeof ${pascal}>;
+${extra}`;
+}
+
+describe("foreign-key inference", () => {
+  let root: string;
+  const write = (name: string, source: string) => {
+    const file = path.join(root, "shared", "models", `${name}.ts`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, source);
+    return file;
+  };
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-fk-"));
+  });
+  afterEach(() => fs.rmSync(root, { recursive: true, force: true }));
+
+  it("does not treat userId as a foreign key when no User model exists", async () => {
+    const info = await parseModelFile(write("probe-item", model("probe-item", "  userId: z.string(),\n  title: z.string(),", "export const partitionKey = '/userId';\n")));
+    const userId = info.fields.find((field) => field.name === "userId")!;
+    expect(userId.isForeignKey).toBeUndefined();
+    expect(userId.referencedModel).toBeUndefined();
+    expect(info.parserWarnings).toEqual([]);
+
+    const list = generateListPage(info, "@sample/shared");
+    const form = generateFormComponent(info, "@sample/shared");
+    expect(list).not.toMatch(/api\/user|userMap/);
+    expect(form).not.toMatch(/api\/user|userOptions/);
+    const schema = JSON.parse(generateOpenApiDocument([info], info)).components.schemas;
+    expect(schema.ProbeItem.properties.userId).toEqual({ type: "string" });
+    expect(Object.keys(schema)).toEqual(["ProbeItem"]);
+  });
+
+  it("infers a foreign key when the referenced model exists", async () => {
+    write("category", model("category", "  name: z.string(),"));
+    const info = await parseModelFile(write("todo", model("todo", "  categoryId: z.string(),")));
+    expect(info.fields.find((field) => field.name === "categoryId")).toMatchObject({ isForeignKey: true, referencedModel: "Category" });
+    expect(generateListPage(info, "@sample/shared")).toContain("/api/category");
+  });
+
+  it("supports explicit references, opt-out, and warns about missing targets", async () => {
+    write("user", model("user", "  name: z.string(),"));
+    const info = await parseModelFile(write("post", model(
+      "post",
+      "  authorId: z.string(),\n  userId: z.string(),\n  reviewerId: z.string(),\n  tagIds: z.array(z.string()),",
+      "export const references = { authorId: 'User', userId: false, reviewerId: 'Reviewer', tagIds: 'Tag', missingId: 'User' };\n"
+    )));
+    const field = (name: string) => info.fields.find((candidate) => candidate.name === name)!;
+    expect(field("authorId")).toMatchObject({ isForeignKey: true, referencedModel: "User" });
+    expect(field("userId").isForeignKey).toBeUndefined();
+    expect(field("reviewerId").isForeignKey).toBeUndefined();
+    expect(field("tagIds").isForeignKey).toBeUndefined();
+    expect(info.parserWarnings).toEqual([
+      "reference-model-not-found: Post.reviewerId references Reviewer, but shared/models has no Reviewer model; it is treated as a plain field.",
+      "reference-field-unsupported: Post.tagIds must be a single string id to reference Tag.",
+      "reference-field-not-found: Post.references declares missingId, but the schema has no such field.",
+    ]);
+  });
+
+  it("declares one lookup per referenced model when several fields reference it", async () => {
+    write("user", model("user", "  name: z.string(),"));
+    const info = await parseModelFile(write("review", model(
+      "review",
+      "  authorId: z.string(),\n  reviewerId: z.string(),",
+      "export const references = { authorId: 'User', reviewerId: 'User' };\n"
+    )));
+    const count = (source: string, text: string) => source.split(text).length - 1;
+    for (const source of [generateListPage(info, "@sample/shared"), generateDetailPage(info, "@sample/shared")]) {
+      expect(count(source, "const [userMap, setUserMap]")).toBe(1);
+      expect(count(source, "fetch('/api/user')")).toBe(1);
+      expect(source).toContain("userMap[item.authorId]".replace("item", source.includes("ListPage") ? "item" : "review"));
+    }
+    const form = generateFormComponent(info, "@sample/shared");
+    expect(count(form, "const [userOptions, setUserOptions]")).toBe(1);
+    expect(count(form, "fetch('/api/user')")).toBe(1);
+    expect(form).toContain('id="authorId"');
+    expect(form).toContain('id="reviewerId"');
+  });
+
+  it("documents the references declaration in capabilities", () => {
+    expect(inspectCapabilities().modelDeclarations.map((declaration) => declaration.name)).toContain("references");
+  });
+});
+
+describe("dynamic schema evaluation metadata", () => {
+  let root: string;
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-dynamic-"));
+    fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "sample", type: "module" }));
+    fs.mkdirSync(path.join(root, "node_modules"), { recursive: true });
+    fs.symlinkSync(path.join(repoRoot, "node_modules", "zod"), path.join(root, "node_modules", "zod"), "junction");
+  });
+  afterEach(() => fs.rmSync(root, { recursive: true, force: true }));
+
+  it("extracts formats, integers, constraints, and inline objects from Zod v4 at runtime", async () => {
+    const file = path.join(root, "shared", "models", "probe-item.ts");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // startsWith() is outside the static subset, which forces runtime evaluation.
+    fs.writeFileSync(file, model("probe-item", [
+      "  userId: z.string().startsWith('u'),",
+      "  title: z.string().min(1).max(5),",
+      "  code: z.string().regex(/^a\\d$/i),",
+      "  tags: z.array(z.string().min(2)).min(1),",
+      "  score: z.number().gt(0).lte(1),",
+      "  edge: z.number().gt(0).min(0).lt(1).max(1),",
+      "  count: z.int(),",
+      "  publishedAt: z.iso.datetime().optional(),",
+      "  createdAt: z.string().optional(),",
+      "  nested: z.object({ x: z.string() }).optional(),",
+    ].join("\n")));
+
+    const info = await parseModelFile(file);
+    const field = (name: string) => info.fields.find((candidate) => candidate.name === name)!;
+    expect(info.parserMode).toBe("dynamic");
+    expect(field("userId").isForeignKey).toBeUndefined();
+    expect(field("title").constraints).toEqual({ minLength: 1, maxLength: 5 });
+    expect(field("code").constraints).toEqual({ pattern: "^a\\d$", patternFlags: "i" });
+    expect(field("tags")).toMatchObject({ isArray: true, constraints: { minLength: 2, minItems: 1 } });
+    expect(field("score").constraints).toEqual({ minimum: 0, exclusiveMinimum: true, maximum: 1 });
+    expect(field("edge").constraints).toEqual({ minimum: 0, exclusiveMinimum: true, maximum: 1, exclusiveMaximum: true });
+    expect(field("count").isInteger).toBe(true);
+    expect(field("publishedAt")).toMatchObject({ format: "date-time", isOptional: true });
+    expect(field("createdAt").format).toBeUndefined();
+    expect(field("nested")).toMatchObject({ type: "object", isOptional: true, objectFields: [expect.objectContaining({ name: "x", type: "string" })] });
+  });
+
+  it("extracts the same metadata from Zod v3 schemas", async () => {
+    const file = path.join(root, "shared", "models", "legacy-item.ts");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, model("legacy-item", [
+      "  title: z.string().startsWith('t').min(2),",
+      "  score: z.number().int().positive(),",
+      "  publishedAt: z.string().datetime().optional(),",
+      "  kind: z.enum(['a', 'b']),",
+      "  nested: z.object({ x: z.string().max(3) }),",
+    ].join("\n")).replace("from 'zod/v4'", "from 'zod'"));
+
+    const info = await parseModelFile(file);
+    const field = (name: string) => info.fields.find((candidate) => candidate.name === name)!;
+    expect(info.parserMode).toBe("dynamic");
+    expect(field("title").constraints).toEqual({ minLength: 2 });
+    expect(field("score")).toMatchObject({ isInteger: true, constraints: { minimum: 0, exclusiveMinimum: true } });
+    expect(field("publishedAt").format).toBe("date-time");
+    expect(field("kind").enumValues).toEqual(["a", "b"]);
+    expect(field("nested").objectFields).toEqual([expect.objectContaining({ name: "x", constraints: { maxLength: 3 } })]);
+  });
+});
+
+describe("Python schema assets", () => {
+  let root: string;
+  const originalCwd = process.cwd();
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-python-schema-"));
+  });
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("keeps declared types and constraints instead of guessing from names", async () => {
+    const file = path.join(root, "shared", "models", "probe-item.ts");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, model("probe-item", [
+      "  title: z.string().min(1),",
+      "  code: z.string().regex(/^a\\d$/i).optional(),",
+      "  tags: z.array(z.string().min(2)).max(3),",
+      "  score: z.number().min(0).max(1),",
+      "  count: z.number().int(),",
+      "  publishedAt: z.iso.datetime().optional(),",
+      "  createdAt: z.string().optional(),",
+      "  nested: z.object({ x: z.string() }).optional(),",
+    ].join("\n")));
+    const info = await parseModelFile(file);
+    process.chdir(root);
+    await generateLanguageSchemaArtifacts([info], info, "functions", "python", new FileOperationSession("commit", root));
+    const modelsDir = path.join(root, "functions", "generated", "python-models", "backend_models", "models");
+    const source = fs.readFileSync(path.join(modelsDir, "probe_item.py"), "utf8");
+
+    expect(source).toContain("created_at: Optional[StrictStr] = Field(default=None, alias=\"createdAt\")");
+    expect(source).toContain("published_at: Optional[datetime] = Field(default=None, alias=\"publishedAt\")");
+    expect(source).toContain("title: StrictStr = Field(min_length=1)");
+    expect(source).toContain("tags: List[Annotated[StrictStr, Field(min_length=2)]] = Field(max_length=3)");
+    expect(source).toContain("score: Union[StrictFloat, StrictInt] = Field(ge=0, le=1)");
+    expect(source).toContain("count: StrictInt");
+    expect(source).toContain("nested: Optional[ProbeItemNested] = Field(default=None)");
+    expect(source).toContain('re.search("^a\\\\d$", item, re.IGNORECASE)');
+    expect(source).toContain("return self.model_dump_json(by_alias=True, exclude_none=True)");
+    expect(fs.readFileSync(path.join(modelsDir, "probe_item_nested.py"), "utf8")).toContain("class ProbeItemNested(BaseModel):");
+  });
+});
+
+describe("Python regex translation", () => {
+  it("translates JavaScript named groups and back-references", () => {
+    expect(toPythonRegex("^(?<code>[A-Z]+)-\\k<code>$")).toEqual({ pattern: "^(?P<code>[A-Z]+)-(?P=code)$" });
+    expect(toPythonRegex("^a\\d$", "i")).toEqual({ pattern: "^a\\d$" });
+  });
+
+  it.each([
+    ["\\p{L}+", "", /Unicode property/],
+    ["(?<=a)b", "", /lookbehind/],
+    ["[^]", "", /empty character classes/],
+    ["\\u{1F600}", "u", /flag\(s\) u|code point/],
+    ["abc", "y", /flag\(s\) y/],
+  ])("reports %s /%s as not enforceable", (pattern, flags, reason) => {
+    const result = toPythonRegex(pattern, flags);
+    expect("unsupported" in result && result.unsupported).toMatch(reason);
+  });
+
+  it("skips unenforceable patterns with a warning and validates raw strings before conversion", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-python-regex-"));
+    const originalCwd = process.cwd();
+    try {
+      const file = path.join(root, "shared", "models", "regex-item.ts");
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, model("regex-item", [
+        "  code: z.string().regex(/^(?<code>[A-Z]+)$/),",
+        "  letters: z.string().regex(/^\\p{L}+$/u),",
+        "  when: z.string().datetime().regex(/Z$/),",
+      ].join("\n")));
+      const info = await parseModelFile(file);
+      expect(getPythonRegexWarnings(info)).toEqual([
+        expect.stringMatching(/^python-regex-not-enforced: RegexItem\.letters uses Unicode property escapes/),
+      ]);
+      process.chdir(root);
+      const session = new FileOperationSession("commit", root);
+      await generateLanguageSchemaArtifacts([info], info, "functions", "python", session);
+      expect(session.warnings).toEqual(getPythonRegexWarnings(info));
+      const source = fs.readFileSync(path.join(root, "functions", "generated", "python-models", "backend_models", "models", "regex_item.py"), "utf8");
+      expect(source).toContain('re.search("^(?P<code>[A-Z]+)$", item, 0)');
+      expect(source).not.toContain("letters_validate_pattern");
+      expect(source).toContain("@field_validator('when', mode='before')");
+      expect(source).toContain("if isinstance(item, str) and not re.search");
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+const pydanticPython = ["python", "python3"].find((command) => spawnSync(command, ["-c", "import pydantic"], { stdio: "ignore" }).status === 0);
+const itWithPydantic = pydanticPython ? it : it.skip;
+
+describe("generated Python model runtime", () => {
+  itWithPydantic("accepts valid regex and timestamp values and rejects invalid ones", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-python-runtime-"));
+    const originalCwd = process.cwd();
+    try {
+      const file = path.join(root, "shared", "models", "regex-item.ts");
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, model("regex-item", [
+        "  code: z.string().regex(/^(?<code>[A-Z]+)$/),",
+        "  when: z.iso.datetime().regex(/Z$/),",
+        "  tags: z.array(z.string().regex(/^t/)),",
+      ].join("\n")));
+      const info = await parseModelFile(file);
+      process.chdir(root);
+      await generateLanguageSchemaArtifacts([info], info, "functions", "python", new FileOperationSession("commit", root));
+      process.chdir(originalCwd);
+      const script = [
+        "import sys",
+        "sys.path.insert(0, 'generated/python-models')",
+        "from backend_models.models.regex_item import RegexItem",
+        "ok = {'id': '1', 'code': 'ABC', 'when': '2024-05-06T07:08:09Z', 'tags': ['t1']}",
+        "RegexItem.from_dict(ok)",
+        "for bad in ({**ok, 'code': 'abc'}, {**ok, 'when': '2024-05-06T07:08:09+09:00'}, {**ok, 'tags': ['x']}):",
+        "    try:",
+        "        RegexItem.from_dict(bad)",
+        "    except ValueError:",
+        "        continue",
+        "    raise SystemExit('accepted ' + repr(bad))",
+        "print('ok')",
+      ].join("\n");
+      const run = spawnSync(pydanticPython!, ["-c", script], { cwd: path.join(root, "functions"), encoding: "utf8" });
+      if (run.status !== 0) throw new Error(`${run.stdout}\n${run.stderr}`);
+      expect(run.stdout.trim()).toBe("ok");
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }, 60000);
+});
+
+describe("user-scoped data warning", () => {
+  const info = (partitionKey: string, fields: string[]) => ({
+    name: "ProbeItem",
+    partitionKey,
+    fields: fields.map((name) => ({ name, type: "string", isOptional: false, isArray: false })),
+  }) as unknown as Parameters<typeof buildUserScopedDataWarning>[0];
+
+  it("warns when the partition key is a per-user id and auth is not configured", () => {
+    expect(buildUserScopedDataWarning(info("/userId", ["id", "userId"]), undefined))
+      .toMatch(/^user-scoped-data-without-auth: ProbeItem\.userId is the partition key and looks like a per-user owner id/);
+    expect(buildUserScopedDataWarning(info("/userId", ["id", "userId"]), { provider: "none" })).toBeDefined();
+  });
+
+  it("warns for owner-like fields that are not the partition key", () => {
+    expect(buildUserScopedDataWarning(info("/id", ["id", "learnerId"]), undefined))
+      .toMatch(/ProbeItem\.learnerId looks like a per-user owner id/);
+  });
+
+  it("stays quiet when authentication is configured or nothing looks user-scoped", () => {
+    expect(buildUserScopedDataWarning(info("/userId", ["id", "userId"]), { provider: "swa" })).toBeUndefined();
+    expect(buildUserScopedDataWarning(info("/userId", ["id", "userId"]), { schemes: { admin: { provider: "swa" } } } as never)).toBeUndefined();
+    expect(buildUserScopedDataWarning(info("/tenantId", ["id", "tenantId", "categoryId"]), undefined)).toBeUndefined();
+  });
+});

package/src/cli/commands/configure-mcp.ts

@@ -0,0 +1,54 @@
+import { Command } from "commander";
+import { ensureSwallowKitProject } from "../../core/config";
+import {
+  MCP_CONFIG_PATH,
+  MCP_LATEST,
+  lookupPublishedLatestVersion,
+  readMcpConfigVersion,
+  resolveMcpPinVersion,
+  writeMcpConfigVersion,
+} from "../../core/project/mcp-config";
+import { resolveProjectSwallowKit } from "../../mcp/version-selection";
+import { parseSemver } from "../../utils/semver";
+import { getSwallowKitVersion } from "../../version";
+
+export interface ConfigureMcpResult {
+  previousVersion: string | null;
+  version: string;
+  reason: string;
+}
+
+export function configureMcp(
+  options: { version?: string; cwd?: string },
+  lookupLatest: (packageName: string) => string | null = lookupPublishedLatestVersion
+): ConfigureMcpResult {
+  const cwd = options.cwd ?? process.cwd();
+  const requested = (options.version ?? "auto").trim();
+  const previousVersion = readMcpConfigVersion(cwd);
+
+  let decision: { version: string; reason: string };
+  if (requested === "auto") {
+    const projectVersion = resolveProjectSwallowKit(cwd)?.version ?? getSwallowKitVersion();
+    decision = resolveMcpPinVersion(projectVersion, lookupLatest("swallowkit"));
+  } else if (requested === MCP_LATEST) {
+    decision = { version: MCP_LATEST, reason: "Explicitly requested latest." };
+  } else if (parseSemver(requested)) {
+    decision = { version: requested, reason: "Explicitly pinned version." };
+  } else {
+    throw new Error(`--version must be "auto", "latest", or a semantic version (got "${requested}").`);
+  }
+
+  writeMcpConfigVersion(cwd, decision.version);
+  return { previousVersion, ...decision };
+}
+
+export const configureMcpCommand = new Command("configure-mcp")
+  .description(`Select the SwallowKit MCP version used by ${MCP_CONFIG_PATH} (auto: latest unless the project is newer)`)
+  .option("--version <version>", "auto | latest | <semver>", "auto")
+  .action((options: { version?: string }) => {
+    ensureSwallowKitProject("configure-mcp");
+    const result = configureMcp({ version: options.version });
+    console.log(`${MCP_CONFIG_PATH}: SWALLOWKIT_MCP_VERSION ${result.previousVersion ?? "(unset)"} -> ${result.version}`);
+    console.log(`Reason: ${result.reason}`);
+    console.log("Restart the MCP server (or reload your agent) to apply the change.");
+  });

package/src/cli/commands/init.ts

@@ -27,6 +27,7 @@ import {
 } from "../../core/scaffold/native-schema-generator";
 import { DEFAULT_AZURE_PYTHON_VERSION } from "../../utils/python-uv";
 import { buildHomePage } from "../../core/project/home-page";
+import { MCP_LATEST, McpPinDecision, lookupPublishedLatestVersion, resolveMcpPinVersion } from "../../core/project/mcp-config";
 
 interface InitOptions {
   name: string;
@@ -802,7 +803,7 @@ export function ensureNextTailwindPostcssConfig(projectDir: string): void {
 `);
 }
 
-export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm'): string {
+export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm', mcpVersion: string = MCP_LATEST): string {
   const { name } = getSwallowKitPackageMetadata();
   return JSON.stringify(
     {
@@ -814,7 +815,7 @@ export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm
             : ["--yes", "--package", `${name}@\${SWALLOWKIT_MCP_VERSION}`, "swallowkit-mcp"],
           cwd: ".",
           env: {
-            SWALLOWKIT_MCP_VERSION: "latest",
+            SWALLOWKIT_MCP_VERSION: mcpVersion,
           },
         },
       },
@@ -824,6 +825,15 @@ export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm
   );
 }
 
+/** latest by default; pinned to this CLI version only when it is newer than published latest. */
+export function selectInitialMcpVersion(
+  lookupLatest: (packageName: string) => string | null = lookupPublishedLatestVersion
+): McpPinDecision {
+  const { name, version } = getSwallowKitPackageMetadata();
+  if (version === MCP_LATEST) return { version: MCP_LATEST, reason: "SwallowKit package metadata is unavailable." };
+  return resolveMcpPinVersion(version, lookupLatest(name));
+}
+
 async function addSwallowKitFiles(
   projectDir: string,
   options: InitOptions,
@@ -1939,11 +1949,16 @@ function createAiAgentFiles(
   console.log('  ✅ .github/copilot-instructions.md (GitHub Copilot adapter)');
   console.log('  ✅ .github/instructions/ (path-specific instructions)');
 
+  const mcpVersion = selectInitialMcpVersion();
   fs.writeFileSync(
     path.join(projectDir, '.mcp.json'),
-    buildSwallowKitMcpProjectConfigSource(pm)
+    buildSwallowKitMcpProjectConfigSource(pm, mcpVersion.version)
+  );
+  console.log(
+    mcpVersion.version === MCP_LATEST
+      ? '  ✅ .mcp.json (project-scoped MCP bootstrap, resolves latest)'
+      : `  ✅ .mcp.json (project-scoped MCP bootstrap, pinned to ${mcpVersion.version}: ${mcpVersion.reason} Run "${runCmd} swallowkit configure-mcp" to re-select later.)`
   );
-  console.log('  ✅ .mcp.json (project-scoped MCP bootstrap)');
 
   writeWorkflowDocs(projectDir, runCmd);
   console.log('  ✅ .swallowkit/workflows/ (agent-agnostic autonomous-loop runbooks)');

package/src/cli/commands/migrations.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { ensureSwallowKitProject } from "../../core/config";
 import { initializeLegacyMigrations } from "../../core/operations/migration-generator";
+import { addModelContainerMigration } from "../../core/operations/model-migration";
 
 export const migrationsCommand = new Command("migrations")
   .description("Manage versioned Azure infrastructure migrations");
@@ -18,3 +19,24 @@ migrationsCommand
     console.log(`Migration baseline 0 created for project ${manifest.projectId}.`);
     console.log("Commit infra/migrations/manifest.json, then run provision with --adopt-existing --baseline 0.");
   });
+
+migrationsCommand
+  .command("add-model")
+  .description("Generate only the Cosmos DB container migration for a model (e.g. after scaffold --skip-infra)")
+  .argument("<model>", "Model file or model name")
+  .option("--dry-run", "Show the planned infra changes without writing anything", false)
+  .action(async (model: string, options: { dryRun?: boolean }) => {
+    ensureSwallowKitProject("migrations add-model");
+    const result = await addModelContainerMigration(model, { dryRun: options.dryRun });
+    for (const operation of result.operations) {
+      if (operation.action !== "skip") console.log(`  ${operation.action.padEnd(7)} ${operation.path}`);
+    }
+    if (!result.migration) {
+      console.log(`No migration needed for ${result.model}: ${result.reason}`);
+    } else if (result.operations.every((operation) => operation.action === "skip")) {
+      console.log(`Migration ${result.migration.version} for ${result.model} already exists: ${result.migration.template}`);
+    } else {
+      console.log(`${result.dryRun ? "Would create" : "Created"} migration ${result.migration.version} for ${result.model}: ${result.migration.template}`);
+      if (!result.dryRun) console.log("Commit the migration, then run provision to plan and apply it.");
+    }
+  });

package/src/cli/commands/provision.ts

@@ -1,7 +1,27 @@
 import { Command } from "commander";
 import prompts from "prompts";
 import { ensureSwallowKitProject } from "../../core/config";
-import { applyProvisionOperation, planProvisionOperation } from "../../core/operations/provision-operations";
+import {
+  INTERACTIVE_PROVISION_RETRY_HINT,
+  ProvisionPlanData,
+  executeProvisionPlan,
+  planProvisionOperation,
+} from "../../core/operations/provision-operations";
+
+export function describeProvisionAction(plan: Pick<ProvisionPlanData, "mode" | "resourceGroup" | "location" | "pendingMigrations">): string {
+  switch (plan.mode) {
+    case "bootstrap":
+      return `Resource group ${plan.resourceGroup} does not exist yet. It will be created in ${plan.location} and the infrastructure in infra/main.bicep will be deployed.`;
+    case "migrate":
+      return `${plan.pendingMigrations.length} infrastructure migration(s) will be deployed to ${plan.resourceGroup}: ${plan.pendingMigrations.map((migration) => `${migration.version}-${migration.slug}`).join(", ")}.`;
+    case "adopt":
+      return `The existing resource group ${plan.resourceGroup} will be recorded as SwallowKit baseline 0. Nothing will be deployed.`;
+    case "reconcile":
+      return `infra/main.bicep will be redeployed to ${plan.resourceGroup}. Template-managed settings may be reset.`;
+    default:
+      return `Resource group ${plan.resourceGroup}:`;
+  }
+}
 
 const PRIMARY_REGIONS = [
   { title: "Japan East (japaneast)", value: "japaneast" },
@@ -70,16 +90,17 @@ export const provisionCommand = new Command("provision")
   .option("--subscription <id>", "Azure subscription ID")
   .option("--location <region>", "Primary location for Functions and Cosmos DB")
   .option("--swa-location <region>", "Static Web App location")
-  .option("--what-if", "Include Azure what-if evidence", false)
+  .option("--what-if", "Include Azure what-if evidence in the preview", false)
   .option("--adopt-existing", "Adopt an existing untagged resource group without deploying main.bicep", false)
   .option("--baseline <version>", "Baseline version for adoption (currently 0)")
   .option("--reconcile", "Explicitly redeploy infra/main.bicep", false)
-  .option("--approve", "Apply the displayed plan without an interactive confirmation", false)
+  .option("--approve", "Run the displayed Azure commands without the confirmation prompt", false)
   .action(async (options: ProvisionCliOptions) => {
     ensureSwallowKitProject("provision");
     const locations = await resolveLocations(options);
     const baseline = options.baseline === undefined ? undefined : Number(options.baseline);
-    const plan = await planProvisionOperation({
+    // Preview in memory: the same Azure checks as the agent workflow, but no saved plan file.
+    const preview = await planProvisionOperation({
       resourceGroup: options.resourceGroup,
       subscription: options.subscription,
       location: locations.location,
@@ -88,37 +109,52 @@ export const provisionCommand = new Command("provision")
       adoptExisting: options.adoptExisting,
       baseline,
       reconcile: options.reconcile,
-    });
+    }, { persist: false });
 
-    console.log(`Provision mode: ${plan.mode}`);
-    for (const warning of plan.warnings) console.warn(`Warning: ${warning}`);
-    if (plan.pendingMigrations.length > 0) {
-      console.log(`Pending migrations: ${plan.pendingMigrations.map((migration) => `${migration.version}-${migration.slug}`).join(", ")}`);
+    for (const warning of preview.warnings) console.warn(`Warning: ${warning}`);
+
+    if (preview.mode === "offline") {
+      console.log([
+        "",
+        "❌ Azure CLI is unavailable, so the current state of Azure could not be checked. Nothing was changed in Azure.",
+        "   1. Make sure `az --version` works in this terminal (install: https://aka.ms/azure-cli).",
+        "   2. Sign in with `az login` (and `az account set --subscription <id>` if needed).",
+        "   3. Run this command again.",
+      ].join("\n"));
+      process.exitCode = 1;
+      return;
     }
-    for (const command of plan.commands) console.log(`  ${command}`);
 
-    if (plan.mode === "adoption-required") {
+    if (preview.mode === "adoption-required") {
       throw new Error('Existing resource group requires: migrations init --legacy-baseline, then provision --adopt-existing --baseline 0 --what-if.');
     }
 
+    if (preview.mode === "noop") {
+      console.log(`Resource group ${preview.resourceGroup} is already up to date. Nothing to do.`);
+      return;
+    }
+
+    console.log(`\n${describeProvisionAction(preview)}`);
+    console.log("The following Azure CLI commands will run:");
+    for (const command of preview.commands) console.log(`  ${command}`);
+
     let approved = options.approve === true;
     if (!approved) {
       if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        throw new Error("Non-interactive provision requires --approve after reviewing the plan.");
+        throw new Error("Non-interactive provision requires --approve after reviewing the commands above.");
       }
       const answer = await prompts({
         type: "confirm",
         name: "approved",
-        message: `Apply the ${plan.mode} plan?`,
+        message: "Run these Azure commands? This may create billable resources.",
         initial: false,
       });
       approved = answer.approved === true;
     }
     if (!approved) {
-      console.log("Provision cancelled.");
+      console.log("Provision cancelled. Nothing was changed in Azure.");
       return;
     }
 
-    const result = await applyProvisionOperation({ planId: plan.planId, approve: true });
-    console.log(`Provision completed (${plan.mode}). ${result.executedCommands.length} command(s) executed.`);
-  });
+    const result = await executeProvisionPlan(preview, { approve: true, retryHint: INTERACTIVE_PROVISION_RETRY_HINT });
+    console.log(`✅ Provisioning completed. ${result.executedCommands.length} Azure CLI command(s) ran.`);  });