swallowkit 1.0.0-beta.8 → 1.0.0

package/src/core/project/agent-templates/azure-functions.instructions.md

@@ -0,0 +1,22 @@
+---
+applyTo: "functions/**"
+---
+
+# Azure Functions — Backend Rules
+
+The root `AGENTS.md` is the canonical contract. Azure Functions own application
+business logic and data access, but generated handlers and contracts may be
+deterministic. Inspect boundaries before choosing an edit location.
+
+- Put custom behavior only in an ai-authored location reported by the current
+  boundary contract.
+- Never directly edit deterministic handlers or generated schema assets.
+- Keep backend contracts aligned with `shared/models/` through MCP-first
+  plan/apply, using the machine interface as fallback.
+- Auto-generate `id`, `createdAt`, and `updatedAt` on the backend. Never trust
+  client-sent values for these fields.
+- Container names use PascalCase plural form and default to `/id` as the
+  partition key unless the source-of-truth model says otherwise.
+- Respect `requires-human` and run SwallowKit verification after changes.
+
+Backend language: {{backendLanguageLabel}}.

package/src/core/project/agent-templates/bff-routes.instructions.md

@@ -0,0 +1,18 @@
+---
+applyTo: "app/api/**"
+---
+
+# BFF API Routes — Rules
+
+The root `AGENTS.md` is the canonical contract. Inspect the current
+responsibility boundary before editing files in this layer.
+
+- `app/api/` is a BFF/proxy layer. Never place business logic, database access,
+  or direct Cosmos DB calls here.
+- Use `callFunction()` from `@/lib/api/call-function` to forward requests to
+  Azure Functions.
+- Input/output validation may use schemas imported from `@{{projectName}}/shared`.
+- Never directly edit a route reported as deterministic. Change its source of
+  truth and use MCP-first plan/apply, with the machine interface as fallback.
+- Edit shared artifacts only outside managed markers.
+- Respect `requires-human` and run SwallowKit verification after changes.

package/src/core/project/agent-templates/copilot-instructions.md

@@ -0,0 +1,27 @@
+# Copilot Instructions
+
+This is a **SwallowKit** project.
+
+Read and follow the root `AGENTS.md` as the canonical project contract.
+
+SwallowKit applies during discovery, requirements clarification, specification,
+planning, ticket decomposition, implementation, verification, and review — not
+only during code generation.
+
+Key rules:
+
+- Inspect current SwallowKit capabilities instead of assuming them.
+- Answer repository- and SwallowKit-inspectable questions before asking the human.
+- Prefer `swallowkit_*` MCP tools when available.
+- Otherwise use `{{runCmd}} swallowkit machine ...`.
+- Inspect responsibility boundaries before editing framework-related files.
+- Never hand-edit deterministic SwallowKit-managed artifacts.
+- Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
+  in swallowkit.config (policies and `swa.allowedProviders` are hand-edited
+  after apply).
+- Use plan/apply for deterministic generation.
+- Respect `requires-human` states and other human approval gates.
+- Run SwallowKit verification before completion.
+
+Task-specific SwallowKit Agent Skills live under `.github/skills/`.
+Agent-agnostic equivalents live under `.swallowkit/workflows/`.

package/src/core/project/agent-templates/shared-models.instructions.md

@@ -0,0 +1,72 @@
+---
+applyTo: "shared/models/**"
+---
+
+# Shared Models — Zod Schema Rules
+
+The root `AGENTS.md` is the canonical contract. Files here are ai-authored
+source-of-truth models, subject to the current result of
+`{{runCmd}} swallowkit machine inspect boundaries`.
+
+## Rules
+
+- Define Zod schemas using `zod/v4` (`import { z } from 'zod/v4'`).
+- Use the Zod pattern where the schema constant and inferred TypeScript type
+  share the same name.
+- `id` is a **required** string field: `id: z.string()`. Generated CRUD, UI,
+  and repositories assume `id` is always present — do NOT make it optional.
+- `createdAt` and `updatedAt` are **optional** string fields
+  (`z.string().optional()`). The backend manages their values.
+- Export a `displayName` string for UI display.
+- Re-export every model from `shared/index.ts`, outside managed markers where
+  applicable.
+- For relationships, use nested schemas rather than duplicating model shapes.
+
+## Optional model declarations (exact formats)
+
+These are the only declarations SwallowKit parses from a model file:
+
+```ts
+// Cosmos DB partition key (default '/id'). Must reference a schema field.
+export const partitionKey = '/learnerId';
+
+// Role-based access control on generated CRUD.
+export const authPolicy = { roles: ['admin'] };
+// or: { read: ['user'], write: ['admin'] } or: { policy: 'adminOnly' }
+
+// Human-readable name for generated UI.
+export const displayName = 'Learner';
+
+// Bind the model to a configured external connector instead of Cosmos DB.
+export const connectorConfig = {
+  connector: 'mysql',
+  table: 'learners',
+  operations: ['list', 'get', 'create', 'update', 'delete'],
+};
+```
+
+The full machine-readable contract:
+`{{runCmd}} swallowkit machine inspect capabilities`
+
+After changing a model, do not manually patch generated artifacts.
+
+## After changing a model
+
+- The shared package is consumed via its built `dist/`. `verify project`
+  rebuilds it automatically, but if you typecheck manually, build the shared
+  package first — "no exported member" errors usually mean a stale `dist/`.
+- If `dev-seeds/` exists, update the seed JSON. Seeds are only applied by
+  running `{{runCmd}} swallowkit dev --seed-env <environment>`; editing the
+  JSON alone does nothing.
+
+Use the `swallowkit-modify-model` Agent Skill when available. Otherwise follow
+`.swallowkit/workflows/modify-model.md`.
+
+The normal agent workflow is:
+
+```text
+inspect drift → plan scaffold → apply scaffold → verify project
+```
+
+Prefer the equivalent `swallowkit_*` MCP tools; use the machine interface as the
+fallback. Stop for any `requires-human` result.

package/src/core/project/artifacts.ts

@@ -0,0 +1,205 @@
+/**
+ * Artifact Ledger — `.swallowkit/artifacts.json`
+ *
+ * SwallowKit が生成・管理するファイルの所有権(Ownership)、内容ハッシュ、
+ * 生成元スキーマのハッシュ、Generator バージョンを記録する台帳。
+ * Git 管理を前提とし、Drift 検出と Plan の衝突判定の基礎データとなる。
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { getSwallowKitVersion } from "../../version";
+import {
+  ArtifactOwnership,
+  RecordedFileOperation,
+  hashFileIfExists,
+} from "../operations/file-session";
+
+export const SWALLOWKIT_ARTIFACTS_PATH = path.join(".swallowkit", "artifacts.json");
+export const SWALLOWKIT_ARTIFACTS_VERSION = 1;
+
+export type ArtifactLastOperation = "create" | "update" | "append" | "delete";
+
+export interface ArtifactRecord {
+  /** Project-relative POSIX path */
+  path: string;
+  ownership: ArtifactOwnership;
+  /** Logical generator name, e.g. "scaffold", "create-model" */
+  generator: string;
+  generatorVersion: string;
+  /** Entity name the artifact was generated from, if any */
+  sourceModel?: string;
+  /** sha256 (LF normalized) of the source model file at generation time */
+  schemaHash?: string;
+  /** sha256 (LF normalized) of the artifact content at generation time */
+  contentHash: string;
+  generatedAt: string;
+  lastOperation: ArtifactLastOperation;
+}
+
+export interface ArtifactLedger {
+  version: number;
+  swallowkitVersion: string;
+  artifacts: ArtifactRecord[];
+}
+
+export function loadArtifactLedger(projectRoot: string = process.cwd()): ArtifactLedger | null {
+  const ledgerPath = path.join(projectRoot, SWALLOWKIT_ARTIFACTS_PATH);
+  if (!fs.existsSync(ledgerPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(ledgerPath, "utf-8")) as ArtifactLedger;
+  } catch {
+    return null;
+  }
+}
+
+export function saveArtifactLedger(ledger: ArtifactLedger, projectRoot: string = process.cwd()): void {
+  const ledgerPath = path.join(projectRoot, SWALLOWKIT_ARTIFACTS_PATH);
+  fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const sorted: ArtifactLedger = {
+    ...ledger,
+    swallowkitVersion: getSwallowKitVersion(),
+    artifacts: [...ledger.artifacts].sort((a, b) => a.path.localeCompare(b.path)),
+  };
+  fs.writeFileSync(ledgerPath, JSON.stringify(sorted, null, 2) + "\n", "utf-8");
+}
+
+export function findArtifactRecord(
+  ledger: ArtifactLedger | null,
+  relativePath: string
+): ArtifactRecord | undefined {
+  return ledger?.artifacts.find((record) => record.path === relativePath);
+}
+
+function toLastOperation(action: RecordedFileOperation["action"]): ArtifactLastOperation | null {
+  switch (action) {
+    case "create":
+      return "create";
+    case "modify":
+      return "update";
+    case "append":
+      return "append";
+    case "delete":
+      return "delete";
+    default:
+      return null;
+  }
+}
+
+export interface RecordArtifactContext {
+  /** sha256 of the source model file, when the operation batch originates from one model */
+  schemaHash?: string;
+  /** Fallback source model name */
+  sourceModel?: string;
+}
+
+/**
+ * セッションで記録された操作を台帳へ反映する。
+ * - skip は台帳更新しない(既存記録があれば schemaHash のみ更新)
+ * - delete は台帳からレコードを削除する
+ */
+export function recordSessionOperations(
+  operations: RecordedFileOperation[],
+  context: RecordArtifactContext = {},
+  projectRoot: string = process.cwd()
+): ArtifactLedger {
+  const ledger: ArtifactLedger = loadArtifactLedger(projectRoot) ?? {
+    version: SWALLOWKIT_ARTIFACTS_VERSION,
+    swallowkitVersion: getSwallowKitVersion(),
+    artifacts: [],
+  };
+
+  const byPath = new Map(ledger.artifacts.map((record) => [record.path, record] as const));
+  const now = new Date().toISOString();
+  const generatorVersion = getSwallowKitVersion();
+
+  for (const operation of operations) {
+    if (operation.action === "delete") {
+      byPath.delete(operation.path);
+      continue;
+    }
+
+    if (operation.action === "skip") {
+      const existing = byPath.get(operation.path);
+      if (existing && context.schemaHash) {
+        existing.schemaHash = context.schemaHash;
+        existing.generatorVersion = generatorVersion;
+      } else if (!existing && operation.newHash) {
+        // 内容一致でも台帳未登録なら記録し、以後の Drift 検出を可能にする
+        byPath.set(operation.path, {
+          path: operation.path,
+          ownership: operation.ownership,
+          generator: operation.generator,
+          generatorVersion,
+          sourceModel: operation.sourceModel ?? context.sourceModel,
+          schemaHash: context.schemaHash,
+          contentHash: operation.newHash,
+          generatedAt: now,
+          lastOperation: "update",
+        });
+      }
+      continue;
+    }
+
+    const lastOperation = toLastOperation(operation.action);
+    if (!lastOperation || !operation.newHash) {
+      continue;
+    }
+
+    byPath.set(operation.path, {
+      path: operation.path,
+      ownership: operation.ownership,
+      generator: operation.generator,
+      generatorVersion,
+      sourceModel: operation.sourceModel ?? context.sourceModel,
+      schemaHash: context.schemaHash,
+      contentHash: operation.newHash,
+      generatedAt: now,
+      lastOperation,
+    });
+  }
+
+  const updated: ArtifactLedger = {
+    version: SWALLOWKIT_ARTIFACTS_VERSION,
+    swallowkitVersion: generatorVersion,
+    artifacts: Array.from(byPath.values()),
+  };
+  saveArtifactLedger(updated, projectRoot);
+  return updated;
+}
+
+export interface InspectedArtifact extends ArtifactRecord {
+  exists: boolean;
+  /** true when the current on-disk content differs from the recorded contentHash */
+  modified: boolean;
+}
+
+export function inspectArtifacts(projectRoot: string = process.cwd()): {
+  ledgerFound: boolean;
+  swallowkitVersion: string | null;
+  artifacts: InspectedArtifact[];
+} {
+  const ledger = loadArtifactLedger(projectRoot);
+  if (!ledger) {
+    return { ledgerFound: false, swallowkitVersion: null, artifacts: [] };
+  }
+
+  const artifacts = ledger.artifacts.map((record) => {
+    const absolutePath = path.join(projectRoot, record.path);
+    const currentHash = hashFileIfExists(absolutePath);
+    return {
+      ...record,
+      exists: currentHash !== null,
+      modified: currentHash !== null && currentHash !== record.contentHash,
+    };
+  });
+
+  return {
+    ledgerFound: true,
+    swallowkitVersion: ledger.swallowkitVersion,
+    artifacts: artifacts.sort((a, b) => a.path.localeCompare(b.path)),
+  };
+}

package/src/core/project/boundaries.ts

@@ -0,0 +1,170 @@
+/**
+ * Responsibility Boundaries — AI の自由生成と SwallowKit の決定論的処理の責任分界点。
+ *
+ * Coding Agent / 自律ループが「どこを自由に書いてよいか」「どこは SwallowKit の
+ * plan/apply に委ねるべきか」を機械可読な契約として取得できるようにする。
+ *
+ * zone:
+ * - deterministic: SwallowKit が決定論的に生成・再生成する領域。手編集しない。
+ * - ai-authored:   AI / 開発者が自由に記述する領域。SwallowKit は上書きしない。
+ * - shared:        マーカー区切りの共有領域。マーカー内は SwallowKit、外は自由。
+ */
+
+import { ArtifactOwnership } from "../operations/file-session";
+import { inspectArtifacts } from "./artifacts";
+
+export type BoundaryZone = "deterministic" | "ai-authored" | "shared";
+
+export type BoundaryEditPolicy =
+  | "never-hand-edit"
+  | "regenerate-via-plan-apply"
+  | "free-edit"
+  | "edit-outside-markers";
+
+export interface OwnershipPolicy {
+  ownership: ArtifactOwnership;
+  zone: BoundaryZone;
+  editPolicy: BoundaryEditPolicy;
+  howToChange: string;
+}
+
+export interface BoundaryPathRule {
+  /** Path prefix or glob-like pattern (documentation purpose; matching is prefix-based) */
+  pattern: string;
+  zone: BoundaryZone;
+  editPolicy: BoundaryEditPolicy;
+  description: string;
+}
+
+export interface BoundaryArtifact {
+  path: string;
+  ownership: ArtifactOwnership;
+  zone: BoundaryZone;
+  editPolicy: BoundaryEditPolicy;
+  generator: string;
+  sourceModel?: string;
+}
+
+export interface BoundariesContract {
+  contractVersion: number;
+  summary: string;
+  ownershipPolicies: OwnershipPolicy[];
+  /** 台帳に載っていないパスの既定規約 */
+  conventionRules: BoundaryPathRule[];
+  /** 台帳に記録された生成物ごとの解決結果 */
+  artifacts: BoundaryArtifact[];
+  guidance: string[];
+}
+
+export const OWNERSHIP_POLICIES: OwnershipPolicy[] = [
+  {
+    ownership: "managed",
+    zone: "deterministic",
+    editPolicy: "regenerate-via-plan-apply",
+    howToChange:
+      "Edit the source model (shared/models/*.ts) or configuration, then run `swallowkit machine plan scaffold <model>` and `apply scaffold`. Hand-edits are detected as drift and require --approve to overwrite.",
+  },
+  {
+    ownership: "generated-once",
+    zone: "ai-authored",
+    editPolicy: "free-edit",
+    howToChange: "Generated once as a starting point. Edit freely; SwallowKit never regenerates it.",
+  },
+  {
+    ownership: "user-owned",
+    zone: "ai-authored",
+    editPolicy: "free-edit",
+    howToChange:
+      "Owned by the developer/AI. SwallowKit only creates the initial version (e.g. model files). Edit freely; managed artifacts are regenerated from it.",
+  },
+  {
+    ownership: "extension-point",
+    zone: "shared",
+    editPolicy: "edit-outside-markers",
+    howToChange:
+      "SwallowKit appends only inside marked sections (e.g. `# SwallowKit scaffold registrations`). Edit anywhere outside the markers freely; do not remove the markers.",
+  },
+  {
+    ownership: "metadata",
+    zone: "deterministic",
+    editPolicy: "never-hand-edit",
+    howToChange: "Managed entirely by SwallowKit tooling (.swallowkit/). Never hand-edit.",
+  },
+];
+
+export const CONVENTION_RULES: BoundaryPathRule[] = [
+  {
+    pattern: ".swallowkit/",
+    zone: "deterministic",
+    editPolicy: "never-hand-edit",
+    description: "SwallowKit metadata (manifest, artifact ledger, plan state). Managed by tooling only.",
+  },
+  {
+    pattern: "shared/models/",
+    zone: "ai-authored",
+    editPolicy: "free-edit",
+    description:
+      "Zod model schemas — the single source of truth. AI/developers author these freely; deterministic generation derives everything else from them.",
+  },
+  {
+    pattern: "infra/main.bicep",
+    zone: "shared",
+    editPolicy: "edit-outside-markers",
+    description: "SwallowKit inserts container modules; other infrastructure edits are free.",
+  },
+  {
+    pattern: "functions/function_app.py",
+    zone: "shared",
+    editPolicy: "edit-outside-markers",
+    description: "SwallowKit appends blueprint registrations under its marker; other edits are free.",
+  },
+  {
+    pattern: "shared/index.ts",
+    zone: "shared",
+    editPolicy: "edit-outside-markers",
+    description: "SwallowKit appends model exports; other exports may be added freely.",
+  },
+  {
+    pattern: "*",
+    zone: "ai-authored",
+    editPolicy: "free-edit",
+    description:
+      "Any path not recorded in the artifact ledger is AI/developer-authored. Business logic, custom pages, custom Functions, and tests belong here.",
+  },
+];
+
+const POLICY_BY_OWNERSHIP = new Map(OWNERSHIP_POLICIES.map((policy) => [policy.ownership, policy] as const));
+
+export const BOUNDARY_GUIDANCE: string[] = [
+  "Author models and business logic freely (ai-authored zone), then let SwallowKit derive CRUD/BFF/UI/infra deterministically via plan/apply.",
+  "Never hand-edit deterministic-zone files; change the model or configuration and regenerate instead.",
+  "Use `swallowkit machine plan scaffold <model>` before applying; a plan with requiresApproval=true means a human (or explicit --approve) must confirm overwriting hand-edited files.",
+  "In shared-zone files, keep SwallowKit markers intact and edit outside them.",
+  "Run `swallowkit machine verify project` after applying changes; use `explain failure` to get repair evidence.",
+];
+
+export function inspectBoundaries(projectRoot: string = process.cwd()): BoundariesContract {
+  const inspected = inspectArtifacts(projectRoot);
+
+  const artifacts: BoundaryArtifact[] = inspected.artifacts.map((artifact) => {
+    const policy = POLICY_BY_OWNERSHIP.get(artifact.ownership);
+    return {
+      path: artifact.path,
+      ownership: artifact.ownership,
+      zone: policy?.zone ?? "ai-authored",
+      editPolicy: policy?.editPolicy ?? "free-edit",
+      generator: artifact.generator,
+      ...(artifact.sourceModel ? { sourceModel: artifact.sourceModel } : {}),
+    };
+  });
+
+  return {
+    contractVersion: 1,
+    summary:
+      "SwallowKit separates deterministic generation (models → CRUD/BFF/UI/infra via plan/apply) from AI free-form authoring (models, business logic, custom code). This contract tells agents which files belong to which side.",
+    ownershipPolicies: OWNERSHIP_POLICIES,
+    conventionRules: CONVENTION_RULES,
+    artifacts,
+    guidance: BOUNDARY_GUIDANCE,
+  };
+}