swallowkit 2.0.0-alpha.2 → 2.0.0-alpha.4

package/src/__tests__/python-venv.test.ts

@@ -0,0 +1,48 @@
+import { execFile } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { ensureUvVirtualEnvironment, getVirtualEnvPythonPath } from "../utils/python-uv";
+
+let mockInterpreterError: Error | null = null;
+jest.mock("child_process", () => ({
+  execFile: jest.fn((
+    _command: string,
+    args: string[],
+    _options: object,
+    callback: (error: Error | null, stdout: string, stderr: string) => void
+  ) => callback(args[0] === "--version" ? mockInterpreterError : null, "Python 3.15.1\n", "")),
+}));
+jest.mock("fs", () => ({ existsSync: jest.fn() }));
+
+describe("uv virtual environment lifecycle", () => {
+  const cwd = path.resolve("python-fixture", "functions");
+  const venv = path.join(cwd, ".venv");
+  const env = { UV_PYTHON: "3.15", UV_PYTHON_DOWNLOADS: "never" };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockInterpreterError = null;
+  });
+
+  it("creates with normal uv selection, then checks that Python can actually execute", async () => {
+    jest.mocked(fs.existsSync).mockReturnValue(false);
+    await expect(ensureUvVirtualEnvironment("uv", venv, cwd, env)).resolves.toBe(getVirtualEnvPythonPath(venv));
+    expect(execFile).toHaveBeenNthCalledWith(1, "uv", ["venv", venv], { cwd, env }, expect.any(Function));
+    expect(execFile).toHaveBeenNthCalledWith(2, getVirtualEnvPythonPath(venv), ["--version"], { cwd, env }, expect.any(Function));
+  });
+
+  it("reuses an existing executable environment without changing its interpreter", async () => {
+    jest.mocked(fs.existsSync).mockReturnValue(true);
+    await ensureUvVirtualEnvironment("uv", venv, cwd, env);
+    expect(execFile).toHaveBeenCalledTimes(1);
+    expect(execFile).toHaveBeenCalledWith(getVirtualEnvPythonPath(venv), ["--version"], { cwd, env }, expect.any(Function));
+  });
+
+  it.each([true, false])("reports blocked Python after checking the environment (existing=%s)", async exists => {
+    jest.mocked(fs.existsSync).mockReturnValue(exists);
+    mockInterpreterError = new Error("Application control blocked this file (os error 4551)");
+    await expect(ensureUvVirtualEnvironment("uv", venv, cwd, env)).rejects.toThrow("os error 4551");
+    expect(jest.mocked(execFile).mock.calls.some(call => call[1]?.includes("--clear"))).toBe(false);
+    expect(execFile).toHaveBeenCalledTimes(exists ? 1 : 2);
+  });
+});

package/src/__tests__/react-dev.test.ts

@@ -0,0 +1,72 @@
+import ts from "typescript";
+import {
+  buildReactDevConfigSource,
+  buildReactDevWatchIgnoredSource,
+} from "../utils/react-dev";
+import { buildReactDevArgs } from "../cli/commands/dev";
+
+describe("React dev watch boundaries", () => {
+  it.each(["C:\\repo\\", "C:\\repo", "/repo/"])(
+    "ignores backend artifacts without excluding frontend or shared sources under %s",
+    root => {
+      const ignored: string[] = new Function("root", `return ${buildReactDevWatchIgnoredSource("root")}`)(root);
+      const normalized = root.replace(/\\/g, "/").replace(/\/$/, "");
+      expect(ignored).toEqual([
+        `${normalized}/functions/**`,
+        `${normalized}/bff/**`,
+        `${normalized}/.uv/**`,
+        `${normalized}/.swallowkit/**`,
+        `${normalized}/shared/dist/**`,
+      ]);
+      expect(ignored.some(value => value.includes("/src/") || value.includes("/shared/models/"))).toBe(false);
+    }
+  );
+
+  function loadWrapper(config: object) {
+    const loadConfigFromFile = jest.fn(async () => ({
+      config,
+      dependencies: ["/repo/vite.config.mts", "/repo/vite-settings.ts"],
+    }));
+    const mergeConfig = jest.fn((base: object, overrides: object) => ({ base, overrides }));
+    const result = { exports: {} as { default: (env: object) => Promise<unknown> } };
+    const source = ts.transpileModule(buildReactDevConfigSource(), {
+      compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+    }).outputText;
+    new Function("require", "exports", source)(
+      () => ({ defineConfig: (value: unknown) => value, loadConfigFromFile, mergeConfig }),
+      result.exports
+    );
+    return { load: result.exports.default, loadConfigFromFile, mergeConfig };
+  }
+
+  it("loads the user's Vite config and merges rather than replacing their watch options", async () => {
+    const config = { plugins: ["user-plugin"], server: { watch: { ignored: ["**/custom/**"], usePolling: true } } };
+    const wrapper = loadWrapper(config);
+    const env = { command: "serve", mode: "development" };
+    await wrapper.load(env);
+    expect(wrapper.loadConfigFromFile).toHaveBeenCalledWith(env, undefined, process.cwd());
+    expect(wrapper.mergeConfig).toHaveBeenCalledWith(config, {
+      plugins: [expect.objectContaining({ name: "swallowkit-dev-watch-boundaries" })],
+      server: { watch: { ignored: expect.arrayContaining([expect.stringContaining("/functions/**")]) } },
+    });
+    const plugin = wrapper.mergeConfig.mock.calls[0][1] as {
+      plugins: Array<{ configResolved: (config: { configFileDependencies: string[] }) => void }>;
+    };
+    const resolved = { configFileDependencies: ["/repo/wrapper.mjs"] };
+    plugin.plugins[0].configResolved(resolved);
+    expect(resolved.configFileDependencies).toContain("/repo/vite.config.mts");
+  });
+
+  it("respects an explicitly disabled watcher", async () => {
+    const config = { server: { watch: null } };
+    const wrapper = loadWrapper(config);
+    await expect(wrapper.load({})).resolves.toBe(config);
+    expect(wrapper.mergeConfig).not.toHaveBeenCalled();
+  });
+
+  it("passes the override config to existing projects without editing their Vite config", () => {
+    expect(buildReactDevArgs("pnpm", "3100", "127.0.0.1", ".swallowkit/config.mjs")).toEqual([
+      "exec", "vite", "--port", "3100", "--host", "127.0.0.1", "--strictPort", "--config", ".swallowkit/config.mjs",
+    ]);
+  });
+});

package/src/__tests__/react.test.ts

@@ -14,6 +14,7 @@ import {
   createReactBffProject,
   buildReactSwaConfig,
 } from "../core/project/react-project";
+import { buildHomePage } from "../core/project/home-page";
 import {
   generateManagedFunctionConfig,
   generateReactBffHelper,
@@ -505,6 +506,24 @@ describe("React project integration", () => {
     ).toBe(false);
   });
 
+  it("generates the shared home page with the selected package manager and Tailwind defaults", () => {
+    createReactProject(project, "sample", "npm");
+    expect(fs.readFileSync(path.join(project, "src", "Home.tsx"), "utf8"))
+      .toBe(buildHomePage("react", "npm"));
+
+    const css = fs.readFileSync(path.join(project, "src", "style.css"), "utf8");
+    expect(css).toContain('@import "tailwindcss"');
+    expect(css).toContain("@media (prefers-color-scheme: dark)");
+    expect(css).toContain("--background: #ffffff");
+    expect(css).toContain("--background: #0a0a0a");
+    expect(css).toContain("--color-background: var(--background)");
+    expect(css).toContain("font-family: Arial, Helvetica, sans-serif");
+    expect(fs.readFileSync(path.join(project, "index.html"), "utf8"))
+      .toContain('class="h-full antialiased"');
+    expect(fs.readFileSync(path.join(project, "vite.config.mts"), "utf8"))
+      .toContain("plugins: [react(), tailwindcss()]");
+  });
+
   it("plans and applies BFF bindings, React pages and metadata through the common path", async () => {
     const plan = await planScaffoldOperation({ model: "todo" });
     expect(plan.requiresApproval).toBe(false);

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.");
+  });