swallowkit 1.0.0-beta.56 → 1.0.0-beta.58

package/src/__tests__/agent-instructions.test.ts

@@ -0,0 +1,237 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  AGENT_TEMPLATE_FILES,
+  AgentInstructionContext,
+  buildAgentsMd,
+  buildClaudeMd,
+  buildCopilotInstructions,
+  buildPathSpecificInstructions,
+  readAgentInstructionTemplate,
+  writeAgentInstructionFiles,
+} from "../core/project/agent-instructions";
+
+const representativeContext: AgentInstructionContext = {
+  projectName: "sample-app",
+  backendLanguage: "typescript",
+  packageManager: "npm",
+};
+
+const repositoryRoot = path.resolve(__dirname, "../..");
+
+describe("coding-agent instruction contract", () => {
+  it("applies SwallowKit before implementation and composes with external processes", () => {
+    const agentsMd = buildAgentsMd(representativeContext);
+
+    expect(agentsMd).toContain("discovery, requirements clarification");
+    expect(agentsMd).toContain("specification, planning, ticket decomposition");
+    expect(agentsMd).toContain("not only during code generation");
+    expect(agentsMd).toContain("How SwallowKit Fits Into the Development Process");
+    expect(agentsMd).toContain("does **not** own the overall software development process");
+    expect(agentsMd).toContain("External development-process skills and SwallowKit are intended to compose");
+  });
+
+  it("requires inspection before questions or design instead of remembered capabilities", () => {
+    const agentsMd = buildAgentsMd(representativeContext);
+
+    expect(agentsMd).toContain("Do Not Assume SwallowKit Capabilities From Memory");
+    expect(agentsMd).toContain("Inspect Before Asking or Designing");
+    expect(agentsMd).toContain("should be answered by the agent instead of being delegated to the human");
+    expect(agentsMd).toContain("npx swallowkit machine inspect project");
+    expect(agentsMd).toContain("npx swallowkit machine inspect entities");
+    expect(agentsMd).toContain("npx swallowkit machine inspect routes");
+    expect(agentsMd).toContain("npx swallowkit machine inspect boundaries");
+  });
+
+  it("defines ownership, vertical slices, plan/apply, verification, and approval gates", () => {
+    const agentsMd = buildAgentsMd(representativeContext);
+
+    expect(agentsMd).toContain("### ai-authored");
+    expect(agentsMd).toContain("### deterministic");
+    expect(agentsMd).toContain("### shared");
+    expect(agentsMd).toContain("vertical slices");
+    expect(agentsMd).toContain("Do not split work into horizontal tickets");
+    expect(agentsMd).toContain("Deterministic Changes: Plan → Apply → Verify");
+    expect(agentsMd).toContain("npx swallowkit machine plan scaffold <model>");
+    expect(agentsMd).toContain("Verification Is a Completion Gate");
+    expect(agentsMd).toContain("semantic code review answers different questions");
+    expect(agentsMd).toContain("When the status is `requires-human`, stop");
+    expect(agentsMd).toContain("never bypass its\napproval gate");
+  });
+
+  it("uses MCP first and the package-manager-specific machine fallback", () => {
+    const npmDocument = buildAgentsMd(representativeContext);
+    const pnpmDocument = buildAgentsMd({
+      ...representativeContext,
+      packageManager: "pnpm",
+    });
+
+    expect(npmDocument).toContain("Prefer the `swallowkit_*` MCP tools when available");
+    expect(npmDocument).toContain("npx swallowkit machine ...");
+    expect(pnpmDocument).toContain("pnpm swallowkit machine ...");
+    expect(pnpmDocument).not.toContain("npx swallowkit machine ...");
+  });
+
+  it("keeps Claude and Copilot as self-identifying adapters to canonical AGENTS.md", () => {
+    const adapters = [
+      buildClaudeMd(representativeContext),
+      buildCopilotInstructions(representativeContext),
+    ];
+
+    for (const adapter of adapters) {
+      expect(adapter).toContain("This is a **SwallowKit** project");
+      expect(adapter).toContain("root `AGENTS.md`");
+      expect(adapter).toContain("canonical project contract");
+      expect(adapter).toContain("discovery");
+      expect(adapter).toContain("specification");
+      expect(adapter).toContain("planning");
+      expect(adapter).toContain("Never hand-edit deterministic SwallowKit-managed artifacts");
+      expect(adapter).toContain("SwallowKit verification");
+    }
+  });
+
+  it("aligns path-specific instructions with the machine plan/apply workflow", () => {
+    const instructions = buildPathSpecificInstructions(representativeContext);
+    const sharedModels = instructions[AGENT_TEMPLATE_FILES.sharedModelsInstructions];
+
+    expect(sharedModels).toContain("swallowkit-modify-model");
+    expect(sharedModels).toContain(".swallowkit/workflows/modify-model.md");
+    expect(sharedModels).toContain("inspect drift → plan scaffold → apply scaffold → verify project");
+    expect(sharedModels).toContain("Prefer the equivalent `swallowkit_*` MCP tools");
+
+    for (const content of Object.values(instructions)) {
+      expect(content).toContain("root `AGENTS.md` is the canonical contract");
+      expect(content).toMatch(/Never|never|do not/);
+      expect(content).toContain("requires-human");
+      expect(content).not.toMatch(/run `(?:npx|pnpm )?swallowkit scaffold/);
+      expect(content).not.toContain("rerunning `swallowkit scaffold`");
+    }
+  });
+
+  it("writes the generated integration files from the builders", () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-agent-docs-"));
+    try {
+      const documents = writeAgentInstructionFiles(tempDir, representativeContext);
+      expect(fs.readFileSync(path.join(tempDir, "AGENTS.md"), "utf-8")).toBe(documents.agentsMd);
+      expect(fs.readFileSync(path.join(tempDir, "CLAUDE.md"), "utf-8")).toBe(documents.claudeMd);
+      expect(
+        fs.readFileSync(path.join(tempDir, ".github", "copilot-instructions.md"), "utf-8")
+      ).toBe(documents.copilotInstructions);
+      for (const [fileName, content] of Object.entries(documents.pathSpecificInstructions)) {
+        expect(
+          fs.readFileSync(path.join(tempDir, ".github", "instructions", fileName), "utf-8")
+        ).toBe(content);
+      }
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("covers the requested model-change, new-feature, BFF, and deployment scenarios", () => {
+    const agentsMd = buildAgentsMd(representativeContext);
+    const pathInstructions = buildPathSpecificInstructions(representativeContext);
+
+    // Scenario A: existing Todo field change.
+    expect(agentsMd).toContain("For an existing model change, the normal pattern is");
+    expect(agentsMd).toContain("edit source-of-truth model");
+    expect(agentsMd).toContain("inspect drift");
+    expect(agentsMd).toContain("verify before final semantic review");
+
+    // Scenario B: new Order behavior starts with discovery and the add-model capability.
+    expect(agentsMd).toContain("requirements clarification");
+    expect(agentsMd).toContain("machine inspect entities");
+    expect(agentsMd).toContain("machine inspect routes");
+    expect(agentsMd).toContain("Use the `swallowkit-add-model` Agent Skill when available");
+
+    // Scenario C: generated BFF logic is redirected to the correct ownership zone.
+    const bff = pathInstructions[AGENT_TEMPLATE_FILES.bffRoutesInstructions];
+    const functions = pathInstructions[AGENT_TEMPLATE_FILES.azureFunctionsInstructions];
+    expect(bff).toContain("Never place business logic, database access");
+    expect(bff).toContain("Never directly edit a route reported as deterministic");
+    expect(functions).toContain("Put custom behavior only in an ai-authored location");
+
+    // Scenario D: a broad deployment request never implies provisioning approval.
+    expect(agentsMd).toContain("A broad request to deploy does not itself grant the explicit");
+    expect(agentsMd).toContain("Use the `swallowkit-provision` Agent Skill or runbook");
+    expect(agentsMd).toContain("When the status is `requires-human`, stop");
+  });
+});
+
+describe("coding-agent documentation synchronization", () => {
+  const englishGuidePath = path.join(repositoryRoot, "docs", "en", "coding-agent-guide.md");
+  const japaneseGuidePath = path.join(repositoryRoot, "docs", "ja", "coding-agent-guide.md");
+
+  it("publishes each complete English original directly from its canonical template", () => {
+    const englishGuide = fs.readFileSync(englishGuidePath, "utf-8");
+    const japaneseGuide = fs.readFileSync(japaneseGuidePath, "utf-8");
+
+    const expectedIncludes = [
+      "AGENTS.md",
+      "CLAUDE.md",
+      "copilot-instructions.md",
+    ];
+    for (const fileName of expectedIncludes) {
+      const include = `<<< ../../src/core/project/agent-templates/${fileName}{md}`;
+      expect(englishGuide).toContain(include);
+      expect(japaneseGuide).toContain(include);
+      expect(readAgentInstructionTemplate(fileName).length).toBeGreaterThan(500);
+    }
+
+    expect(englishGuide).toContain("complete English templates");
+    expect(englishGuide).toContain("not\nabridged excerpts");
+    expect(japaneseGuide).toContain("抜粋ではありません");
+  });
+
+  it("keeps the Japanese AGENTS.md translation aligned by canonical section", () => {
+    const source = readAgentInstructionTemplate(AGENT_TEMPLATE_FILES.agentsMd);
+    const translation = fs.readFileSync(
+      path.join(repositoryRoot, "docs", "ja", "generated-agent-docs", "AGENTS.ja.md"),
+      "utf-8"
+    );
+    const sourceSections = [...source.matchAll(/^## (.+)$/gm)].map((match) => match[1]);
+    const translatedSourceSections = [
+      ...translation.matchAll(/^<!-- source-section: (.+) -->$/gm),
+    ].map((match) => match[1]);
+
+    expect(translatedSourceSections).toEqual(sourceSections);
+  });
+
+  it("exposes matching major EN/JA guide topics and both sidebar entries", () => {
+    const englishGuide = fs.readFileSync(englishGuidePath, "utf-8");
+    const japaneseGuide = fs.readFileSync(japaneseGuidePath, "utf-8");
+    const vitepressConfig = fs.readFileSync(
+      path.join(repositoryRoot, "docs", ".vitepress", "config.mts"),
+      "utf-8"
+    );
+
+    for (const topic of [
+      "Generated agent integration files",
+      "SwallowKit across the development lifecycle",
+      "Inspect before asking or designing",
+      "Responsibility boundary",
+      "Planning and ticketing",
+      "Implementation workflow",
+      "Verification versus semantic review",
+      "Human approval",
+      "Composing with external development processes",
+    ]) {
+      expect(englishGuide.toLowerCase()).toContain(topic.toLowerCase());
+    }
+    for (const topic of [
+      "生成される Agent integration files",
+      "開発ライフサイクル全体での SwallowKit",
+      "質問・設計の前に inspect する",
+      "Responsibility boundary",
+      "Planning と ticketing",
+      "Implementation workflow",
+      "Verification と semantic review の違い",
+      "Human approval",
+      "外部 development process との composition",
+    ]) {
+      expect(japaneseGuide).toContain(topic);
+    }
+    expect(vitepressConfig).toContain("/en/coding-agent-guide");
+    expect(vitepressConfig).toContain("/ja/coding-agent-guide");
+  });
+});

package/src/__tests__/init.test.ts

@@ -40,6 +40,7 @@ export default nextConfig;
     const updated = injectSwallowKitNextConfig(original, "sample-app");
 
     expect(updated).toContain("output: 'standalone'");
+    expect(updated).toContain("agentRules: false");
     expect(updated).toContain("transpilePackages: ['@sample-app/shared']");
     expect(updated).toContain("serverExternalPackages: ['applicationinsights', 'diagnostic-channel-publishers']");
     expect(updated).not.toContain("turbopackUseSystemTlsCerts");
@@ -57,6 +58,7 @@ module.exports = nextConfig;
     const updated = injectSwallowKitNextConfig(original, "sample-app");
 
     expect(updated).toContain("transpilePackages: ['@sample-app/shared']");
+    expect(updated).toContain("agentRules: false");
     expect(updated).toContain("module.exports = nextConfig;");
   });
 

package/src/__tests__/plan-apply.test.ts

@@ -1,6 +1,8 @@
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import * as childProcess from "child_process";
+import { EventEmitter } from "events";
 import { runMachineCli } from "../machine";
 
 jest.mock("child_process", () => {
@@ -63,6 +65,49 @@ function createProjectFixture(rootDir: string): void {
   );
 }
 
+function createNativeBackendFixture(rootDir: string, backendLanguage: "csharp" | "python"): void {
+  createProjectFixture(rootDir);
+  writeFile(
+    path.join(rootDir, "swallowkit.config.js"),
+    `module.exports = {
+  database: {
+    connectionString: 'AccountEndpoint=https://example.local;',
+  },
+  backend: {
+    language: '${backendLanguage}',
+  },
+  api: {
+    endpoint: '/api/_swallowkit',
+  },
+};
+`
+  );
+
+  if (backendLanguage === "csharp") {
+    writeFile(path.join(rootDir, "functions", "SwallowKit.Functions.csproj"), "<Project />\n");
+  } else {
+    writeFile(
+      path.join(rootDir, "functions", "function_app.py"),
+      "from azure.functions import FunctionApp\n\napp = FunctionApp()\n\n# SwallowKit scaffold registrations\n"
+    );
+  }
+}
+
+function mockSuccessfulNativeCodegen(): () => void {
+  const spawnSyncMock = childProcess.spawnSync as unknown as any;
+  const spawnMock = childProcess.spawn as unknown as any;
+  spawnSyncMock.mockReturnValue({ status: 0 });
+  spawnMock.mockImplementation(() => {
+    const child = new EventEmitter() as childProcess.ChildProcess;
+    process.nextTick(() => child.emit("close", 0));
+    return child;
+  });
+  return () => {
+    spawnMock.mockReset();
+    spawnSyncMock.mockReset();
+  };
+}
+
 async function runMachine(argv: string[]): Promise<{ response: any; exitCode: number }> {
   const writes: string[] = [];
   const originalWrite = process.stdout.write.bind(process.stdout);
@@ -163,6 +208,93 @@ describe("plan / apply / drift / verify machine commands", () => {
     expect(fs.existsSync(path.join(tempDir, ".swallowkit", "state", "plans", `${planId}.json`))).toBe(false);
   });
 
+  it.each([
+    {
+      backendLanguage: "csharp" as const,
+      modelPath: "functions/generated/csharp-models/src/SwallowKitBackendModels/Model/Todo.cs",
+    },
+    {
+      backendLanguage: "python" as const,
+      modelPath: "functions/generated/python-models/backend_models/models/todo.py",
+    },
+  ])(
+    "includes $backendLanguage native schema artifacts in plan, ledger, and approval checks",
+    async ({ backendLanguage, modelPath }) => {
+      createNativeBackendFixture(tempDir, backendLanguage);
+      const restoreCodegenMocks = mockSuccessfulNativeCodegen();
+
+      try {
+        const plan = await runMachine(machineArgs("plan", "scaffold", "todo", "--api-only"));
+
+        expect(plan.response).toEqual(expect.objectContaining({ ok: true, status: "complete" }));
+        expect(plan.exitCode).toBe(0);
+        expect(plan.response.data.warnings).not.toEqual(
+          expect.arrayContaining([expect.stringContaining("external-codegen")])
+        );
+        expect(plan.response.data.operations).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({ path: "functions/openapi/todo.openapi.json", action: "create" }),
+            expect.objectContaining({ path: modelPath, action: "create", ownership: "managed" }),
+          ])
+        );
+        expect(fs.existsSync(path.join(tempDir, "functions", "openapi"))).toBe(false);
+        expect(fs.existsSync(path.join(tempDir, modelPath))).toBe(false);
+        expect(childProcess.spawn).not.toHaveBeenCalled();
+
+        const applied = await runMachine(
+          machineArgs("apply", "scaffold", "--plan", plan.response.data.planId)
+        );
+        expect(applied.exitCode).toBe(0);
+        expect(fs.existsSync(path.join(tempDir, modelPath))).toBe(true);
+
+        const ledger = JSON.parse(
+          fs.readFileSync(path.join(tempDir, ".swallowkit", "artifacts.json"), "utf-8")
+        );
+        expect(ledger.artifacts).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({ path: modelPath, ownership: "managed", generator: "native-schema" }),
+          ])
+        );
+
+        fs.appendFileSync(path.join(tempDir, modelPath), "\n// customized\n");
+        const denied = await runMachine(machineArgs("apply", "scaffold", "todo", "--api-only"));
+        expect(denied.exitCode).toBe(1);
+        expect(denied.response.error.code).toBe("approval-required");
+        expect(denied.response.error.details.conflicts).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({ path: modelPath, conflictReason: "modified-after-generation" }),
+          ])
+        );
+      } finally {
+        restoreCodegenMocks();
+      }
+    }
+  );
+
+  it("leaves the project untouched when the native toolchain validation fails on apply", async () => {
+    createNativeBackendFixture(tempDir, "csharp");
+    const spawnSyncMock = childProcess.spawnSync as unknown as any;
+    // dotnet --version が失敗 → .NET SDK 不在としてプリフライトで拒否される
+    spawnSyncMock.mockReturnValue({ status: 1 });
+
+    try {
+      const { response, exitCode } = await runMachine(machineArgs("apply", "scaffold", "todo", "--api-only"));
+
+      expect(exitCode).toBe(1);
+      expect(response.ok).toBe(false);
+      expect(response.error.message).toContain(".NET SDK is required");
+
+      expect(fs.existsSync(path.join(tempDir, "app"))).toBe(false);
+      expect(fs.existsSync(path.join(tempDir, "lib"))).toBe(false);
+      expect(fs.existsSync(path.join(tempDir, "functions", "openapi"))).toBe(false);
+      expect(fs.existsSync(path.join(tempDir, "functions", "generated"))).toBe(false);
+      expect(fs.existsSync(path.join(tempDir, "functions", "Crud"))).toBe(false);
+      expect(fs.existsSync(path.join(tempDir, ".swallowkit", "artifacts.json"))).toBe(false);
+    } finally {
+      spawnSyncMock.mockReset();
+    }
+  });
+
   it("rejects a stale plan when files change after planning", async () => {
     createProjectFixture(tempDir);
 
@@ -186,6 +318,41 @@ describe("plan / apply / drift / verify machine commands", () => {
     expect(fs.existsSync(path.join(tempDir, "app"))).toBe(false);
   });
 
+  it("rejects a native backend plan when a nested model changes after planning", async () => {
+    createNativeBackendFixture(tempDir, "csharp");
+    writeFile(path.join(tempDir, "shared", "models", "member.ts"), createModelSource("Member"));
+    writeFile(
+      path.join(tempDir, "shared", "models", "todo.ts"),
+      `import { z } from 'zod/v4';
+import { Member } from './member';
+
+export const Todo = z.object({
+  id: z.string(),
+  name: z.string().min(1),
+  member: Member,
+});
+
+export type Todo = z.infer<typeof Todo>;
+`
+    );
+
+    const plan = await runMachine(machineArgs("plan", "scaffold", "todo", "--api-only"));
+    expect(plan.response).toEqual(expect.objectContaining({ ok: true, status: "complete" }));
+    expect(plan.response.data.fingerprints["shared/models/member.ts"]).toMatch(/^[0-9a-f]{64}$/);
+
+    writeFile(
+      path.join(tempDir, "shared", "models", "member.ts"),
+      createModelSource("Member", "\n  role: z.string().optional(),")
+    );
+
+    const applied = await runMachine(
+      machineArgs("apply", "scaffold", "--plan", plan.response.data.planId)
+    );
+    expect(applied.exitCode).toBe(1);
+    expect(applied.response.error.code).toBe("stale-plan");
+    expect(applied.response.error.details.changedFiles).toContain("shared/models/member.ts");
+  });
+
   it("requires approval to overwrite files modified after generation, then applies with --approve", async () => {
     createProjectFixture(tempDir);
 

package/src/__tests__/scaffold.test.ts

@@ -167,7 +167,7 @@ describe("native schema generators", () => {
   });
 
   it("builds NSwag arguments for model-only C# generation", () => {
-    const outputPath = path.join("C:\\temp\\generated\\csharp-models", ".native-temp", "Contracts.cs");
+    const outputPath = path.join(os.tmpdir(), "swallowkit-csharp-codegen-example", "Contracts.cs");
     const args = getCSharpNativeGeneratorArgs("C:\\temp\\todo.openapi.json", outputPath);
 
     expect(args.slice(0, 4)).toEqual(["tool", "run", "nswag", "openapi2csclient"]);
@@ -178,7 +178,7 @@ describe("native schema generators", () => {
   });
 
   it("builds datamodel-code-generator arguments for python assets", () => {
-    const outputPath = path.join("C:\\temp\\generated\\python-models", ".native-temp", "models.py");
+    const outputPath = path.join(os.tmpdir(), "swallowkit-python-codegen-example", "models.py");
     const args = getPythonNativeGeneratorArgs("C:\\temp\\todo.openapi.json", outputPath);
 
     expect(args).toEqual(