swallowkit 1.0.0-beta.6 → 1.0.0-beta.60

package/src/core/project/capabilities.ts

@@ -0,0 +1,193 @@
+/**
+ * Capabilities — 「SwallowKit に何ができるか」の機械可読な自己記述。
+ *
+ * inspect project/boundaries/infra が「今の状態」を返すのに対し、
+ * inspect capabilities は「モデルで宣言できるもの・認証の正しい導入手順・
+ * 生成 CRUD の守備範囲・シード適用方法」など、状態に依存しない
+ * フレームワーク仕様を返す。Coding Agent がドキュメント外の知識を
+ * 推測で埋めるのを構造的に防ぐことが目的。
+ */
+
+import { getSwallowKitVersion } from "../../version";
+
+export interface CapabilityModelDeclaration {
+  name: string;
+  required: boolean;
+  description: string;
+  format: string;
+  notes?: string[];
+}
+
+export interface CapabilityAuthProvider {
+  provider: string;
+  description: string;
+  postApplySteps: string[];
+}
+
+export interface CapabilitiesContract {
+  contractVersion: number;
+  swallowkitVersion: string;
+  modelDeclarations: CapabilityModelDeclaration[];
+  authentication: {
+    correctWorkflow: string[];
+    rules: string[];
+    providers: CapabilityAuthProvider[];
+    authorizationPolicies: {
+      semantics: string;
+      configExample: string;
+      handEditAllowed: boolean;
+    };
+  };
+  generatedCrud: {
+    guarantees: string[];
+    notGuaranteed: string[];
+    guidance: string[];
+  };
+  sharedModels: {
+    idFieldRule: string;
+    buildNote: string;
+  };
+  seeding: {
+    createTemplates: string;
+    applySeeds: string;
+    notes: string[];
+  };
+  machineCommands: string[];
+  verifyChecks: {
+    defaultChecks: string[];
+    optInChecks: string[];
+    customChecks: string;
+  };
+}
+
+export function inspectCapabilities(): CapabilitiesContract {
+  return {
+    contractVersion: 1,
+    swallowkitVersion: getSwallowKitVersion(),
+    modelDeclarations: [
+      {
+        name: "schema",
+        required: true,
+        description:
+          "Zod object schema; the schema constant and the inferred type share the same PascalCase name. `id` MUST be a required string — generated CRUD, UI, and repositories assume it is always present. Only `createdAt` / `updatedAt` are optional (backend-managed).",
+        format:
+          "export const Todo = z.object({ id: z.string(), title: z.string().min(1), createdAt: z.string().optional(), updatedAt: z.string().optional() });\nexport type Todo = z.infer<typeof Todo>;",
+      },
+      {
+        name: "displayName",
+        required: false,
+        description: "Human-readable name used by generated UI. Defaults to the model name.",
+        format: "export const displayName = 'Todo';",
+      },
+      {
+        name: "partitionKey",
+        required: false,
+        description:
+          "Cosmos DB partition key path for the generated container. Must start with '/' and reference a field that exists in the schema. Defaults to '/id'.",
+        format: "export const partitionKey = '/learnerId';",
+        notes: ["The referenced field (e.g. learnerId) must be declared in the Zod schema."],
+      },
+      {
+        name: "authPolicy",
+        required: false,
+        description:
+          "Role-based access control metadata applied to the generated CRUD Functions. `roles` guards all operations; `read`/`write` guard per-operation; `policy` references a named authorization policy from swallowkit.config auth.authorization.policies.",
+        format:
+          "export const authPolicy = { roles: ['admin'] };\n// or per-operation:\nexport const authPolicy = { read: ['user'], write: ['admin'] };\n// or a named policy:\nexport const authPolicy = { policy: 'adminOnly' };",
+      },
+      {
+        name: "connectorConfig",
+        required: false,
+        description:
+          "Binds the model to a configured external connector (RDB / API) instead of Cosmos DB. The connector must exist in swallowkit.config connectors.",
+        format:
+          "export const connectorConfig = {\n  connector: 'mysql',\n  table: 'todos',\n  operations: ['list', 'get', 'create', 'update', 'delete'],\n};",
+      },
+    ],
+    authentication: {
+      correctWorkflow: [
+        "1. plan auth --provider <custom-jwt|swa|external-token> [--scheme <name>] [--allowed-providers <csv>] — computes the change plan; SwallowKit writes auth.schemes into swallowkit.config for you.",
+        "2. apply auth --plan <planId> — generates auth code and appends the scheme to swallowkit.config.",
+        "3. Hand-edit swallowkit.config auth.authorization.policies to define named policies (the config is an extension point; this edit is expected).",
+        "4. For swa schemes: set swa.allowedProviders via --allowed-providers at plan time, or hand-edit it in the config after apply.",
+        "5. For external-token schemes: implement the generated verifier stub — it fails closed (throws) until implemented.",
+        "6. Re-run plan/apply scaffold for models that need auth guards, then verify project.",
+      ],
+      rules: [
+        "NEVER hand-write auth.schemes entries in swallowkit.config — plan/apply auth owns them and duplicate names abort with 'already exists'.",
+        "authorization.policies and swa.allowedProviders ARE hand-edited after apply (extension-point edits).",
+        "Verifier stubs pass typecheck and verify; a passing verify does NOT mean external-token auth works end-to-end.",
+      ],
+      providers: [
+        {
+          provider: "custom-jwt",
+          description: "Login/logout/me endpoints backed by an RDB user table, bcrypt password check, HS256 JWT.",
+          postApplySteps: ["Set JWT_SECRET in functions/local.settings.json.", "Ensure the user table matches auth.customJwt config."],
+        },
+        {
+          provider: "swa",
+          description: "Azure Static Web Apps built-in auth (EasyAuth). Principal arrives via x-ms-client-principal.",
+          postApplySteps: [
+            "Set swa.allowedProviders (e.g. ['github']) via --allowed-providers or by hand-editing the config; generated login URLs use the first entry.",
+          ],
+        },
+        {
+          provider: "external-token",
+          description: "Bearer tokens issued by an external IdP (LINE, Auth0, ...). SwallowKit generates a fail-closed verifier stub.",
+          postApplySteps: [
+            "Implement the generated verifier (extension point / generated-once; edit freely).",
+            "Implement the frontend token adapter (lib/auth/**/token-adapter.ts).",
+          ],
+        },
+        {
+          provider: "none",
+          description: "Disables authentication in the config.",
+          postApplySteps: [],
+        },
+      ],
+      authorizationPolicies: {
+        semantics:
+          "A named policy lists which schemes may satisfy it and which roles are required. Generated guards call requireAuth(request, policyName). Exactly one scheme must match the presented credentials.",
+        configExample:
+          "auth: {\n  schemes: { admin: { provider: 'swa', swa: { allowedProviders: ['github'] } }, api: { provider: 'external-token' } },\n  authorization: {\n    defaultPolicy: 'anonymous',\n    policies: {\n      adminOnly: { schemes: ['admin'], roles: ['administrator'] },\n      learner: { schemes: ['api'] },\n    },\n  },\n}",
+        handEditAllowed: true,
+      },
+    },
+    generatedCrud: {
+      guarantees: [
+        "Generated CRUD endpoints enforce the model's authPolicy (authentication + role checks).",
+        "Zod validation runs before persistence.",
+      ],
+      notGuaranteed: [
+        "Owner scoping: generated CRUD does NOT restrict rows to the authenticated principal. Any authenticated caller passing the policy can read/write any document.",
+      ],
+      guidance: [
+        "For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
+      ],
+    },
+    sharedModels: {
+      idFieldRule: "id: z.string() (required). createdAt/updatedAt: z.string().optional(). The backend owns their values.",
+      buildNote:
+        "verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build the shared package first (errors like \"no exported member\" usually mean a stale dist).",
+    },
+    seeding: {
+      createTemplates: "swallowkit create-dev-seeds <environment> — writes dev-seeds/<environment>/<model>.json templates.",
+      applySeeds: "swallowkit dev --seed-env <environment> — applies the seed JSON to the local Cosmos DB emulator at dev startup.",
+      notes: ["Editing dev-seeds/*.json alone does nothing; seeds are only applied via dev --seed-env."],
+    },
+    machineCommands: [
+      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities",
+      "validate project",
+      "generate model <names...> | generate scaffold <model>",
+      "plan scaffold <models...> | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc>",
+      "apply scaffold [models...] --plan <id> [--approve] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve",
+      "verify project [--checks <ids>] [--compact]",
+      "explain failure [--check <id>]",
+    ],
+    verifyChecks: {
+      defaultChecks: ["structure", "drift", "typecheck"],
+      optInChecks: ["build", "lint", "test"],
+      customChecks: "swallowkit.config verify.checks: [{ id, command, title?, timeoutMs? }]",
+    },
+  };
+}

package/src/core/project/drift.ts

@@ -0,0 +1,202 @@
+/**
+ * Drift Detection — 生成物と現在のプロジェクト状態の乖離を検出する。
+ *
+ * 検出対象:
+ * - schema-drift:       スキーマ変更後に生成物が再生成されていない
+ * - generator-drift:    Generator (SwallowKit) のバージョンが生成時から変わっている
+ * - artifact-modified:  生成後にファイルが手動変更されている(再生成で失われる可能性)
+ * - artifact-missing:   台帳に記録された生成物が存在しない
+ * - manifest-drift:     Manifest と実際のプロジェクト構造が一致していない
+ */
+
+import * as path from "path";
+import { getSwallowKitVersion } from "../../version";
+import { hashFileIfExists } from "../operations/file-session";
+import { ArtifactRecord, loadArtifactLedger } from "./artifacts";
+import { buildProjectManifest, readProjectManifest, SWALLOWKIT_MANIFEST_PATH } from "./manifest";
+
+export type DriftKind =
+  | "schema-drift"
+  | "generator-drift"
+  | "artifact-modified"
+  | "artifact-missing"
+  | "manifest-drift";
+
+export type DriftSeverity = "error" | "warning" | "info";
+
+export interface DriftFinding {
+  kind: DriftKind;
+  severity: DriftSeverity;
+  message: string;
+  path?: string;
+  entity?: string;
+  expected?: string;
+  actual?: string;
+  repairAction: string;
+}
+
+export interface DriftDetectionResult {
+  ledgerFound: boolean;
+  findings: DriftFinding[];
+  checkedArtifacts: number;
+}
+
+function detectArtifactDrift(
+  record: ArtifactRecord,
+  projectRoot: string,
+  findings: DriftFinding[]
+): void {
+  const absolutePath = path.join(projectRoot, record.path);
+  const currentHash = hashFileIfExists(absolutePath);
+
+  if (currentHash === null) {
+    findings.push({
+      kind: "artifact-missing",
+      severity: "warning",
+      message: `Generated artifact is missing: ${record.path}`,
+      path: record.path,
+      entity: record.sourceModel,
+      expected: record.contentHash,
+      actual: "missing",
+      repairAction: record.sourceModel
+        ? `Run "swallowkit machine apply scaffold ${record.sourceModel}" to regenerate the artifact.`
+        : "Re-run the SwallowKit generator that produced this artifact.",
+    });
+    return;
+  }
+
+  if (currentHash !== record.contentHash) {
+    const isUserEditable = record.ownership === "user-owned" || record.ownership === "generated-once";
+    findings.push({
+      kind: "artifact-modified",
+      severity: isUserEditable ? "info" : "warning",
+      message: isUserEditable
+        ? `${record.ownership} artifact has been edited after generation (expected): ${record.path}`
+        : `${record.ownership} artifact has been modified after generation; regenerating will require approval: ${record.path}`,
+      path: record.path,
+      entity: record.sourceModel,
+      expected: record.contentHash,
+      actual: currentHash,
+      repairAction: isUserEditable
+        ? "No action required. Edits to this ownership class are expected."
+        : "Keep the customization (plan/apply will flag a conflict) or revert the file to the generated content.",
+    });
+  }
+}
+
+function detectSchemaDrift(
+  records: ArtifactRecord[],
+  projectRoot: string,
+  findings: DriftFinding[]
+): void {
+  const bySchema = new Map<string, { schemaHash: string; sourceModel?: string; paths: string[] }>();
+
+  for (const record of records) {
+    if (!record.schemaHash || !record.sourceModel) continue;
+    const key = record.sourceModel;
+    const entry = bySchema.get(key) ?? { schemaHash: record.schemaHash, sourceModel: record.sourceModel, paths: [] };
+    entry.schemaHash = record.schemaHash;
+    entry.paths.push(record.path);
+    bySchema.set(key, entry);
+  }
+
+  for (const [modelName, entry] of bySchema) {
+    // モデルファイルは shared/models/<kebab>.ts 規約
+    const kebab = modelName
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+      .toLowerCase();
+    const modelPath = path.join(projectRoot, "shared", "models", `${kebab}.ts`);
+    const currentSchemaHash = hashFileIfExists(modelPath);
+    if (currentSchemaHash === null) {
+      continue; // モデルファイルが見つからない場合は manifest-drift 側で検出される
+    }
+    if (currentSchemaHash !== entry.schemaHash) {
+      findings.push({
+        kind: "schema-drift",
+        severity: "warning",
+        message: `Model "${modelName}" changed after its artifacts were generated (${entry.paths.length} artifact(s) are stale).`,
+        path: `shared/models/${kebab}.ts`,
+        entity: modelName,
+        expected: entry.schemaHash,
+        actual: currentSchemaHash,
+        repairAction: `Run "swallowkit machine plan scaffold ${kebab}" then apply to regenerate artifacts for ${modelName}.`,
+      });
+    }
+  }
+}
+
+function detectGeneratorDrift(records: ArtifactRecord[], findings: DriftFinding[]): void {
+  const currentVersion = getSwallowKitVersion();
+  const staleVersions = new Map<string, number>();
+
+  for (const record of records) {
+    if (record.generatorVersion !== currentVersion) {
+      staleVersions.set(record.generatorVersion, (staleVersions.get(record.generatorVersion) ?? 0) + 1);
+    }
+  }
+
+  for (const [version, count] of staleVersions) {
+    findings.push({
+      kind: "generator-drift",
+      severity: "info",
+      message: `${count} artifact(s) were generated with SwallowKit ${version}; current version is ${currentVersion}.`,
+      expected: currentVersion,
+      actual: version,
+      repairAction: "Re-run scaffold for affected models to regenerate artifacts with the current generator version.",
+    });
+  }
+}
+
+async function detectManifestDrift(projectRoot: string, findings: DriftFinding[]): Promise<void> {
+  const stored = readProjectManifest(projectRoot);
+  if (!stored) {
+    return;
+  }
+
+  const { manifest: rebuilt } = await buildProjectManifest(projectRoot);
+  const sameEntitySet =
+    JSON.stringify(stored.entities.map((entity) => entity.name).sort()) ===
+    JSON.stringify(rebuilt.entities.map((entity) => entity.name).sort());
+  const sameRouteSet =
+    JSON.stringify(stored.routes.map((route) => route.name).sort()) ===
+    JSON.stringify(rebuilt.routes.map((route) => route.name).sort());
+
+  if (!sameEntitySet || !sameRouteSet) {
+    findings.push({
+      kind: "manifest-drift",
+      severity: "warning",
+      message: `${SWALLOWKIT_MANIFEST_PATH} does not match the current project structure.`,
+      path: SWALLOWKIT_MANIFEST_PATH.replace(/\\/g, "/"),
+      repairAction: "Run any SwallowKit generator command (or scaffold) to refresh the project manifest.",
+    });
+  }
+}
+
+export async function detectDrift(projectRoot: string = process.cwd()): Promise<DriftDetectionResult> {
+  const findings: DriftFinding[] = [];
+  const ledger = loadArtifactLedger(projectRoot);
+
+  if (ledger) {
+    for (const record of ledger.artifacts) {
+      detectArtifactDrift(record, projectRoot, findings);
+    }
+    detectSchemaDrift(ledger.artifacts, projectRoot, findings);
+    detectGeneratorDrift(ledger.artifacts, findings);
+  } else {
+    findings.push({
+      kind: "artifact-modified",
+      severity: "info",
+      message: "No artifact ledger (.swallowkit/artifacts.json) found. Artifact-level drift is unknown for this project.",
+      repairAction: "Run scaffold (or apply) once with the current SwallowKit version to initialize the artifact ledger.",
+    });
+  }
+
+  await detectManifestDrift(projectRoot, findings);
+
+  return {
+    ledgerFound: ledger !== null,
+    findings: findings.sort((a, b) => a.kind.localeCompare(b.kind) || (a.path ?? "").localeCompare(b.path ?? "")),
+    checkedArtifacts: ledger?.artifacts.length ?? 0,
+  };
+}

package/src/core/project/infra.ts

@@ -0,0 +1,196 @@
+/**
+ * Infra Inspection — infra/ 配下の Bicep 資産を決定論的に解析する。
+ * az CLI やネットワークアクセスは一切使わない(純粋なテキスト解析)。
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+export interface InfraParam {
+  name: string;
+  type: string;
+  defaultValue?: string;
+  description?: string;
+  allowed?: string[];
+}
+
+export interface InfraModule {
+  symbolicName: string;
+  source: string;
+  deploymentName?: string;
+  condition?: string;
+}
+
+export interface InfraOutput {
+  name: string;
+  type: string;
+}
+
+export interface InfraContainer {
+  file: string;
+  /** main.bicep に module として配線済みか */
+  wired: boolean;
+}
+
+export interface InfraInspection {
+  hasInfraDirectory: boolean;
+  mainBicep: {
+    exists: boolean;
+    path: string;
+    params: InfraParam[];
+    modules: InfraModule[];
+    outputs: InfraOutput[];
+  };
+  parametersFile: {
+    exists: boolean;
+    path: string;
+  };
+  moduleFiles: string[];
+  containers: InfraContainer[];
+  boundary: {
+    zone: "shared";
+    note: string;
+  };
+  warnings: string[];
+}
+
+function parseParams(content: string): InfraParam[] {
+  const params: InfraParam[] = [];
+  const lines = content.split(/\r?\n/);
+  let pendingDescription: string | undefined;
+  let pendingAllowed: string[] | undefined;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    const descMatch = /^@description\('([^']*)'\)/.exec(line);
+    if (descMatch) {
+      pendingDescription = descMatch[1];
+      continue;
+    }
+
+    if (/^@allowed\(/.test(line)) {
+      // 単一行 @allowed(['a', 'b']) と複数行の両方に対応
+      let block = line;
+      let j = i;
+      while (!block.includes(")") && j + 1 < lines.length) {
+        j++;
+        block += "\n" + lines[j].trim();
+      }
+      i = j;
+      pendingAllowed = Array.from(block.matchAll(/'([^']*)'/g)).map((m) => m[1]);
+      continue;
+    }
+
+    const paramMatch = /^param\s+(\w+)\s+(\w+)(?:\s*=\s*(.+))?$/.exec(line);
+    if (paramMatch) {
+      params.push({
+        name: paramMatch[1],
+        type: paramMatch[2],
+        ...(paramMatch[3] ? { defaultValue: paramMatch[3].trim() } : {}),
+        ...(pendingDescription ? { description: pendingDescription } : {}),
+        ...(pendingAllowed ? { allowed: pendingAllowed } : {}),
+      });
+      pendingDescription = undefined;
+      pendingAllowed = undefined;
+      continue;
+    }
+
+    if (line !== "" && !line.startsWith("@") && !line.startsWith("//")) {
+      pendingDescription = undefined;
+      pendingAllowed = undefined;
+    }
+  }
+
+  return params;
+}
+
+function parseModules(content: string): InfraModule[] {
+  const modules: InfraModule[] = [];
+  const moduleRegex = /module\s+(\w+)\s+'([^']+)'\s*=\s*(?:if\s*\(([^)]*)\)\s*)?\{/g;
+  for (const match of content.matchAll(moduleRegex)) {
+    const rest = content.slice((match.index ?? 0) + match[0].length);
+    const nameMatch = /name:\s*'([^']*)'/.exec(rest.slice(0, 200));
+    modules.push({
+      symbolicName: match[1],
+      source: match[2],
+      ...(nameMatch ? { deploymentName: nameMatch[1] } : {}),
+      ...(match[3] ? { condition: match[3].trim() } : {}),
+    });
+  }
+  return modules;
+}
+
+function parseOutputs(content: string): InfraOutput[] {
+  const outputs: InfraOutput[] = [];
+  for (const match of content.matchAll(/^output\s+(\w+)\s+(\w+)\s*=/gm)) {
+    outputs.push({ name: match[1], type: match[2] });
+  }
+  return outputs;
+}
+
+function listBicepFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".bicep"))
+    .sort();
+}
+
+export function inspectInfra(projectRoot: string = process.cwd()): InfraInspection {
+  const infraDir = path.join(projectRoot, "infra");
+  const mainBicepPath = path.join(infraDir, "main.bicep");
+  const parametersPath = path.join(infraDir, "main.parameters.json");
+  const warnings: string[] = [];
+
+  const hasInfraDirectory = fs.existsSync(infraDir);
+  const mainExists = fs.existsSync(mainBicepPath);
+
+  let params: InfraParam[] = [];
+  let modules: InfraModule[] = [];
+  let outputs: InfraOutput[] = [];
+  let mainContent = "";
+
+  if (mainExists) {
+    mainContent = fs.readFileSync(mainBicepPath, "utf-8");
+    params = parseParams(mainContent);
+    modules = parseModules(mainContent);
+    outputs = parseOutputs(mainContent);
+  } else if (hasInfraDirectory) {
+    warnings.push("infra/main.bicep not found; provisioning is not possible until it is restored.");
+  }
+
+  const moduleFiles = listBicepFiles(path.join(infraDir, "modules")).map((f) => `infra/modules/${f}`);
+
+  const containers: InfraContainer[] = listBicepFiles(path.join(infraDir, "containers")).map((f) => {
+    const wired = mainContent.includes(`containers/${f}`);
+    if (!wired) {
+      warnings.push(
+        `container-not-wired: infra/containers/${f} is not referenced from infra/main.bicep; run scaffold again or wire it manually.`
+      );
+    }
+    return { file: `infra/containers/${f}`, wired };
+  });
+
+  return {
+    hasInfraDirectory,
+    mainBicep: {
+      exists: mainExists,
+      path: "infra/main.bicep",
+      params,
+      modules,
+      outputs,
+    },
+    parametersFile: {
+      exists: fs.existsSync(parametersPath),
+      path: "infra/main.parameters.json",
+    },
+    moduleFiles,
+    containers,
+    boundary: {
+      zone: "shared",
+      note: "infra/main.bicep is an extension point: scaffold appends container modules deterministically; humans may edit other sections. infra/containers/*.bicep are managed (regenerated by scaffold).",
+    },
+    warnings,
+  };
+}