swallowkit 1.0.0-beta.8 → 1.0.0

package/src/__tests__/__snapshots__/nextjs-generator.test.ts.snap

@@ -1,7 +1,7 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`generateBFFCallFunction generates call function helper code 1`] = `
-"import { NextRequest, NextResponse } from 'next/server';
+"import { NextResponse } from 'next/server';
 import { z } from 'zod/v4';
 
 /**
@@ -23,13 +23,24 @@ function getFunctionsBaseUrl(): string {
   return process.env.BACKEND_FUNCTIONS_BASE_URL || process.env.FUNCTIONS_BASE_URL || 'http://localhost:7071';
 }
 
-interface CallFunctionConfig<TInput = any, TOutput = any> {
+function isLocalFunctionsUrl(url: string): boolean {
+  return url.startsWith('http://localhost:') || url.startsWith('http://127.0.0.1:');
+}
+
+function getFunctionsKeyHeaders(functionsBaseUrl: string): Record<string, string> {
+  const key = process.env.BACKEND_FUNCTIONS_KEY;
+  if (key) return { 'x-functions-key': key };
+  if (isLocalFunctionsUrl(functionsBaseUrl)) return {};
+  throw new Error('BACKEND_FUNCTIONS_KEY is required for non-local Functions calls');
+}
+
+interface CallFunctionConfig<TInput = unknown, TOutput = unknown> {
   /** HTTP メソッド */
   method: 'GET' | 'POST' | 'PUT' | 'DELETE';
   /** Azure Functions のパス (例: '/api/todo', '/api/todo/123') */
   path: string;
   /** リクエストボディ (POST/PUT 用) */
-  body?: any;
+  body?: unknown;
   /** 入力バリデーション用 Zod スキーマ (省略時はバリデーションなし) */
   inputSchema?: z.ZodSchema<TInput>;
   /** 出力バリデーション用 Zod スキーマ (省略時はそのまま返す) */
@@ -38,7 +49,7 @@ interface CallFunctionConfig<TInput = any, TOutput = any> {
   successStatus?: number;
 }
 
-export async function callFunction<TInput = any, TOutput = any>(
+export async function callFunction<TInput = unknown, TOutput = unknown>(
   config: CallFunctionConfig<TInput, TOutput>
 ): Promise<NextResponse> {
   const { method, path, body, inputSchema, responseSchema, successStatus = 200 } = config;
@@ -61,11 +72,12 @@ export async function callFunction<TInput = any, TOutput = any>(
     // Azure Functions を呼び出し
     const functionsBaseUrl = getFunctionsBaseUrl();
     const url = functionsBaseUrl + path;
+    const keyHeaders = getFunctionsKeyHeaders(functionsBaseUrl);
     console.log(\`[BFF] \${method} \${url}\`);
 
     const response = await fetch(url, {
       method,
-      headers: { 'Content-Type': 'application/json' },
+      headers: { 'Content-Type': 'application/json', ...keyHeaders },
       body: validatedBody !== undefined ? JSON.stringify(validatedBody) : undefined,
     });
 
@@ -100,10 +112,10 @@ export async function callFunction<TInput = any, TOutput = any>(
     }
 
     return NextResponse.json(data, { status: successStatus });
-  } catch (error: any) {
+  } catch (error) {
     console.error(\`[BFF] Error:\`, error);
     return NextResponse.json(
-      { error: error.message || 'Internal server error' },
+      { error: error instanceof Error ? error.message : 'Internal server error' },
       { status: 500 }
     );
   }

package/src/__tests__/__snapshots__/ui-generator.test.ts.snap

@@ -9,6 +9,7 @@ import Link from 'next/link';
 import { z } from 'zod/v4';
 import { todoSchema } from '@myapp/shared';
 
+
 type Todo = z.infer<typeof todoSchema>;
 
 export default function TodoDetailPage() {
@@ -19,6 +20,7 @@ export default function TodoDetailPage() {
   const [error, setError] = useState<string | null>(null);
 
 
+
   useEffect(() => {
     const id = params?.id as string;
     if (!id) return;
@@ -51,8 +53,8 @@ export default function TodoDetailPage() {
       if (!res.ok) throw new Error('Failed to delete todo');
 
       router.push('/todo');
-    } catch (err: any) {
-      alert(\`Error: \${err.message}\`);
+    } catch (err) {
+      alert(\`Error: \${err instanceof Error ? err.message : String(err)}\`);
     }
   };
 
@@ -141,18 +143,22 @@ exports[`generateEditPage generates edit page (snapshot) 1`] = `
 "'use client';
 
 import { useEffect, useState } from 'react';
-import { useParams } from 'next/navigation';
+import { useParams, useRouter } from 'next/navigation';
 import TodoForm from '../../_components/TodoForm';
 import { z } from 'zod/v4';
 import { todoSchema } from '@myapp/shared';
 
+
 type Todo = z.infer<typeof todoSchema>;
 
 export default function EditTodoPage() {
   const params = useParams();
+
   const [todo, setTodo] = useState<Todo | null>(null);
   const [loading, setLoading] = useState(true);
 
+
+
   useEffect(() => {
     const id = params?.id as string;
     if (!id) return;
@@ -235,7 +241,7 @@ export default function TodoForm({ initialData, isEdit = false }: TodoFormProps)
 
     try {
       // Array フィールドをカンマ区切りから配列に変換
-      const submitData: any = { ...formData };
+      const submitData: Record<string, unknown> = { ...formData };
 
 
 
@@ -259,17 +265,17 @@ export default function TodoForm({ initialData, isEdit = false }: TodoFormProps)
       }
 
       router.push('/todo');
-    } catch (err: any) {
-      if (err.issues) {
+    } catch (err) {
+      if (err instanceof z.ZodError) {
         // Zod validation errors
         const fieldErrors: Record<string, string> = {};
-        err.issues.forEach((error: any) => {
-          const field = error.path[0];
-          fieldErrors[field] = error.message;
+        err.issues.forEach((issue) => {
+          const field = String(issue.path[0]);
+          fieldErrors[field] = issue.message;
         });
         setErrors(fieldErrors);
       } else {
-        alert(\`Error: \${err.message}\`);
+        alert(\`Error: \${err instanceof Error ? err.message : String(err)}\`);
       }
       setLoading(false);
     }
@@ -360,6 +366,7 @@ import Link from 'next/link';
 import { z } from 'zod/v4';
 import { todoSchema } from '@myapp/shared';
 
+
 type Todo = z.infer<typeof todoSchema>;
 
 export default function TodoListPage() {
@@ -368,6 +375,7 @@ export default function TodoListPage() {
   const [error, setError] = useState<string | null>(null);
 
 
+
   useEffect(() => {
     fetch('/api/todo')
       .then((res) => {
@@ -397,8 +405,8 @@ export default function TodoListPage() {
       if (!res.ok) throw new Error('Failed to delete todo');
 
       setTodos(todos.filter((item) => item.id !== id));
-    } catch (err: any) {
-      alert(\`Error: \${err.message}\`);
+    } catch (err) {
+      alert(\`Error: \${err instanceof Error ? err.message : String(err)}\`);
     }
   };
 

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