swallowkit 1.0.0-beta.8 → 1.0.0

package/src/core/project/agent-instructions.ts

@@ -0,0 +1,167 @@
+import * as fs from "fs";
+import * as path from "path";
+import { BackendLanguage } from "../../types";
+import { PackageManager, getCommands } from "../../utils/package-manager";
+
+export interface AgentInstructionContext {
+  projectName: string;
+  backendLanguage: BackendLanguage;
+  packageManager: PackageManager;
+}
+
+export interface AgentInstructionDocuments {
+  agentsMd: string;
+  claudeMd: string;
+  copilotInstructions: string;
+  pathSpecificInstructions: Record<string, string>;
+}
+
+export const AGENT_TEMPLATE_FILES = {
+  agentsMd: "AGENTS.md",
+  claudeMd: "CLAUDE.md",
+  copilotInstructions: "copilot-instructions.md",
+  sharedModelsInstructions: "shared-models.instructions.md",
+  bffRoutesInstructions: "bff-routes.instructions.md",
+  azureFunctionsInstructions: "azure-functions.instructions.md",
+} as const;
+
+const BACKEND_LANGUAGE_LABELS: Record<BackendLanguage, string> = {
+  typescript: "TypeScript",
+  csharp: "C#",
+  python: "Python",
+};
+
+function getTemplatePath(fileName: string): string {
+  const candidates = [
+    path.join(__dirname, "agent-templates", fileName),
+    path.join(__dirname, "../../../src/core/project/agent-templates", fileName),
+  ];
+  const templatePath = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!templatePath) {
+    throw new Error(`Agent instruction template not found: ${fileName}`);
+  }
+  return templatePath;
+}
+
+export function readAgentInstructionTemplate(fileName: string): string {
+  return fs.readFileSync(getTemplatePath(fileName), "utf-8").replace(/\r\n/g, "\n");
+}
+
+function getFunctionsStructureLine(backendLanguage: BackendLanguage): string {
+  if (backendLanguage === "typescript") {
+    return "│   └── src/               # HTTP trigger handlers with Cosmos DB bindings";
+  }
+  if (backendLanguage === "csharp") {
+    return "│   ├── Crud/              # C# HTTP trigger handlers\n│   └── generated/         # Native-generated C# schema assets";
+  }
+  return "│   ├── blueprints/        # Python HTTP trigger handlers\n│   └── generated/         # Native-generated Python schema assets";
+}
+
+function getBackendRules(backendLanguage: BackendLanguage): string {
+  if (backendLanguage === "typescript") {
+    return [
+      "- All backend business logic and data access live in `functions/src/`.",
+      "- Prefer Azure Functions Cosmos DB input/output bindings for reads and writes.",
+      "- Use the Cosmos DB SDK directly only where bindings do not support the operation, such as deletes.",
+      "- Validate data against the shared Zod schemas before persistence.",
+    ].join("\n");
+  }
+  return [
+    "- All backend business logic and data access live in `functions/`.",
+    `- SwallowKit derives OpenAPI and native ${BACKEND_LANGUAGE_LABELS[backendLanguage]} schema assets from the Zod source of truth.`,
+    "- Keep custom business logic in ai-authored locations identified by the current boundary contract.",
+  ].join("\n");
+}
+
+function interpolateTemplate(template: string, context: AgentInstructionContext): string {
+  const runCmd = getCommands(context.packageManager).exec;
+  const replacements: Record<string, string> = {
+    projectName: context.projectName,
+    backendLanguageLabel: BACKEND_LANGUAGE_LABELS[context.backendLanguage],
+    functionsStructureLine: getFunctionsStructureLine(context.backendLanguage),
+    backendRules: getBackendRules(context.backendLanguage),
+    pm: context.packageManager,
+    runCmd,
+  };
+
+  const result = template.replace(/\{\{([A-Za-z]+)\}\}/g, (placeholder, key: string) => {
+    const replacement = replacements[key];
+    if (replacement === undefined) {
+      throw new Error(`Unknown Agent instruction placeholder: ${placeholder}`);
+    }
+    return replacement;
+  });
+
+  if (/\{\{[^}]+\}\}/.test(result)) {
+    throw new Error("Unresolved Agent instruction template placeholder");
+  }
+  return result;
+}
+
+function buildTemplate(fileName: string, context: AgentInstructionContext): string {
+  return interpolateTemplate(readAgentInstructionTemplate(fileName), context);
+}
+
+export function buildAgentsMd(context: AgentInstructionContext): string {
+  return buildTemplate(AGENT_TEMPLATE_FILES.agentsMd, context);
+}
+
+export function buildClaudeMd(context: AgentInstructionContext): string {
+  return buildTemplate(AGENT_TEMPLATE_FILES.claudeMd, context);
+}
+
+export function buildCopilotInstructions(context: AgentInstructionContext): string {
+  return buildTemplate(AGENT_TEMPLATE_FILES.copilotInstructions, context);
+}
+
+export function buildPathSpecificInstructions(
+  context: AgentInstructionContext
+): Record<string, string> {
+  return {
+    [AGENT_TEMPLATE_FILES.sharedModelsInstructions]: buildTemplate(
+      AGENT_TEMPLATE_FILES.sharedModelsInstructions,
+      context
+    ),
+    [AGENT_TEMPLATE_FILES.bffRoutesInstructions]: buildTemplate(
+      AGENT_TEMPLATE_FILES.bffRoutesInstructions,
+      context
+    ),
+    [AGENT_TEMPLATE_FILES.azureFunctionsInstructions]: buildTemplate(
+      AGENT_TEMPLATE_FILES.azureFunctionsInstructions,
+      context
+    ),
+  };
+}
+
+export function buildAgentInstructionDocuments(
+  context: AgentInstructionContext
+): AgentInstructionDocuments {
+  return {
+    agentsMd: buildAgentsMd(context),
+    claudeMd: buildClaudeMd(context),
+    copilotInstructions: buildCopilotInstructions(context),
+    pathSpecificInstructions: buildPathSpecificInstructions(context),
+  };
+}
+
+export function writeAgentInstructionFiles(
+  projectDir: string,
+  context: AgentInstructionContext
+): AgentInstructionDocuments {
+  const documents = buildAgentInstructionDocuments(context);
+  fs.writeFileSync(path.join(projectDir, "AGENTS.md"), documents.agentsMd, "utf-8");
+  fs.writeFileSync(path.join(projectDir, "CLAUDE.md"), documents.claudeMd, "utf-8");
+
+  const githubDir = path.join(projectDir, ".github");
+  const instructionsDir = path.join(githubDir, "instructions");
+  fs.mkdirSync(instructionsDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(githubDir, "copilot-instructions.md"),
+    documents.copilotInstructions,
+    "utf-8"
+  );
+  for (const [fileName, content] of Object.entries(documents.pathSpecificInstructions)) {
+    fs.writeFileSync(path.join(instructionsDir, fileName), content, "utf-8");
+  }
+  return documents;
+}

package/src/core/project/agent-templates/AGENTS.md

@@ -0,0 +1,504 @@
+# AGENTS.md
+
+This project was generated by **SwallowKit**.
+
+SwallowKit is part of this project's architecture and development workflow.
+Treat it as a standing constraint during discovery, requirements clarification,
+specification, planning, ticket decomposition, implementation, verification,
+and review — not only during code generation.
+
+## How SwallowKit Fits Into the Development Process
+
+SwallowKit does **not** own the overall software development process.
+
+If the user or another Agent Skill or framework defines a process for
+requirements discovery, specification, planning, ticketing, TDD,
+implementation, or review, continue to follow that process.
+
+Use SwallowKit as the authoritative project-specific layer for:
+
+- inspecting the current project
+- understanding entities, routes, infrastructure, and responsibility boundaries
+- determining which artifacts may be edited directly
+- performing deterministic generation through plan/apply
+- detecting drift
+- verifying the resulting project
+- enforcing human approval gates for sensitive operations
+
+External development-process skills and SwallowKit are intended to compose.
+
+A process skill decides **how to proceed**.
+SwallowKit determines **how this SwallowKit project can be changed safely and reproducibly**.
+
+## Do Not Assume SwallowKit Capabilities From Memory
+
+SwallowKit evolves over time.
+
+Do not rely on model knowledge or assumptions about what SwallowKit can or
+cannot generate.
+
+When a SwallowKit capability, project structure, or ownership boundary affects
+a design decision, inspect the current project and the currently available
+SwallowKit interfaces before deciding.
+
+Prefer the `swallowkit_*` MCP tools when available.
+
+If MCP is unavailable, use the machine interface:
+
+```bash
+{{runCmd}} swallowkit machine ...
+```
+
+The machine interface is the fallback Agent-facing interface and returns
+structured `status` / `nextActions` suitable for autonomous workflows.
+
+## Inspect Before Asking or Designing
+
+When a task may affect SwallowKit-managed application structure, inspect the
+project before asking the human questions or committing to an implementation
+design.
+
+Use only the inspections relevant to the task. Typical inspections include:
+
+```bash
+{{runCmd}} swallowkit machine inspect project
+{{runCmd}} swallowkit machine inspect entities
+{{runCmd}} swallowkit machine inspect routes
+{{runCmd}} swallowkit machine inspect boundaries
+{{runCmd}} swallowkit machine inspect drift
+{{runCmd}} swallowkit machine inspect infra
+{{runCmd}} swallowkit machine inspect capabilities
+```
+
+`inspect capabilities` answers "what can SwallowKit do" (supported model
+declarations with exact formats, the correct auth-introduction workflow, what
+generated CRUD does and does not guarantee, how seeds are applied). Use it
+instead of guessing or grepping SwallowKit internals.
+
+Use the equivalent `swallowkit_*` MCP tools when available.
+
+Questions that can be answered from the repository or SwallowKit inspection
+should be answered by the agent instead of being delegated to the human.
+
+Examples:
+
+- Do not ask how generated CRUD layers should be wired if SwallowKit already
+  defines and generates them.
+- Do not propose editing a generated file until responsibility boundaries have
+  been checked.
+- Do not assume an infrastructure capability is unavailable before inspecting
+  the current SwallowKit project and available operations.
+
+## Specification and Planning Guidance
+
+When producing or refining a specification:
+
+- describe user-visible behavior and domain intent
+- define acceptance criteria and important test seams
+- treat SwallowKit's architecture and responsibility boundaries as
+  implementation constraints
+- avoid prematurely describing generated artifacts as manually implemented
+  components
+- do not duplicate work that SwallowKit can deterministically derive from its
+  source of truth
+
+For example, if adding a model field causes SwallowKit to regenerate backend,
+BFF, UI, and infrastructure artifacts, the specification should primarily
+describe the desired end-to-end behavior and the SwallowKit constraint.
+
+It should not imply that every generated layer is an independent manual
+implementation decision.
+
+If whether SwallowKit supports the desired behavior affects the specification,
+inspect the current capabilities before finalizing the spec.
+
+## Ticket Decomposition Guidance
+
+Prefer independently verifiable **vertical slices** of user or system behavior.
+
+Do not split work into horizontal tickets such as:
+
+- schema ticket
+- backend ticket
+- BFF ticket
+- UI ticket
+- infrastructure ticket
+
+merely because those artifacts exist in separate layers.
+
+When SwallowKit deterministically produces those layers, keep them inside the
+same vertical slice whenever they represent one end-to-end behavior.
+
+Example:
+
+```text
+Add priority support to Todo
+  ├─ update the source-of-truth model
+  ├─ use SwallowKit plan/apply to realign managed artifacts
+  ├─ add any required ai-authored business logic
+  ├─ add/update tests
+  └─ verify the project
+```
+
+Ticket boundaries should reflect independently valuable and verifiable
+behavior, not SwallowKit's generated file structure.
+
+## Responsibility Boundary
+
+Before making file-level implementation decisions, inspect the current
+machine-readable boundary contract:
+
+```bash
+{{runCmd}} swallowkit machine inspect boundaries
+```
+
+Treat its current result as authoritative.
+
+The general ownership model is:
+
+### ai-authored
+
+The agent may edit these directly.
+
+Typical examples include:
+
+- source-of-truth models
+- custom business logic
+- custom pages/components
+- tests
+
+### deterministic
+
+Do not hand-edit these artifacts.
+
+They are generated and owned by SwallowKit. Change the appropriate source of
+truth or configuration, then use SwallowKit plan/apply to regenerate them.
+
+Managed artifacts are tracked by SwallowKit metadata such as
+`.swallowkit/artifacts.json`.
+
+### shared
+
+Edit only outside SwallowKit-managed markers.
+
+Always inspect the current boundary contract instead of relying solely on the
+examples in this document.
+
+## Deterministic Changes: Plan → Apply → Verify
+
+For autonomous or agent-driven generation, prefer the SwallowKit two-phase
+workflow.
+
+```text
+inspect
+   ↓
+plan
+   ↓
+evaluate conflicts / approval requirements
+   ↓
+apply
+   ↓
+verify
+```
+
+Example:
+
+```bash
+{{runCmd}} swallowkit machine plan scaffold <model>
+{{runCmd}} swallowkit machine apply scaffold --plan <planId>
+{{runCmd}} swallowkit machine verify project
+```
+
+Do not bypass plan/apply by manually editing deterministic artifacts.
+
+If a plan reports conflicts, determine whether existing hand-written behavior
+must be moved to an ai-authored location or whether overwrite approval is
+required.
+
+Never invent or implicitly grant human approval.
+
+## Model Changes
+
+For an existing model change, the normal pattern is:
+
+```text
+edit source-of-truth model
+        ↓
+inspect drift
+        ↓
+plan scaffold
+        ↓
+resolve conflicts / approvals if any
+        ↓
+apply
+        ↓
+verify
+```
+
+Use the `swallowkit-modify-model` Agent Skill when available.
+
+Otherwise read and follow the equivalent runbook under
+`.swallowkit/workflows/`.
+
+Never repair schema drift by directly patching SwallowKit-managed artifacts.
+
+Additional model-change facts:
+
+- The shared package is consumed through its built `dist/`. `verify project`
+  rebuilds it automatically before typecheck; when typechecking manually,
+  build the shared package first (stale `dist/` shows up as
+  "no exported member" errors).
+- Seed JSON under `dev-seeds/` is only applied by
+  `{{runCmd}} swallowkit dev --seed-env <environment>`; editing the files
+  alone does nothing.
+
+## New Models / CRUD Features
+
+Use the `swallowkit-add-model` Agent Skill when available.
+
+Otherwise follow the equivalent runbook under `.swallowkit/workflows/`.
+
+The agent may author domain-specific schema fields and custom behavior, but
+SwallowKit should generate framework-owned CRUD artifacts.
+
+Do not manually recreate boilerplate that SwallowKit owns.
+
+## Authentication
+
+Authentication is a **plan/apply operation**, not a free-form config edit.
+Ownership of `swallowkit.config` is split:
+
+- `auth.schemes` — owned by SwallowKit. **Always start with
+  `{{runCmd}} swallowkit machine plan auth --provider <p> [--scheme <name>]`.
+  Never hand-write `auth.schemes` entries**; apply auth appends them, and a
+  hand-written scheme makes the plan fail with "already exists".
+- `auth.authorization.policies` and `swa.allowedProviders` — hand-edited
+  **after** apply (the config is an extension point; this edit is expected).
+  `swa.allowedProviders` can also be set at plan time with
+  `--allowed-providers github,aad`.
+
+After `apply auth`, follow the returned `nextActions`:
+
+1. Define `auth.authorization.policies` referencing the new scheme.
+2. For `swa`: confirm `swa.allowedProviders`; generated login URLs use it.
+3. For `external-token`: implement the generated verifier stub. It fails
+   closed, and **verify passes with the stub in place** — a green verify does
+   not mean external-token auth works end-to-end (`verify project` surfaces a
+   `auth-verifier-stub` warning while the stub is unmodified).
+4. Re-run plan/apply scaffold for models that need auth guards, then verify.
+
+Use the `swallowkit-add-auth` Agent Skill or the
+`.swallowkit/workflows/add-auth.md` runbook when available.
+
+### Generated CRUD scope
+
+Generated CRUD endpoints enforce the model's `authPolicy`
+(authentication + roles) — **they do NOT scope data to the authenticated
+user**. Any caller passing the policy can read or write any document. 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 the generated
+write endpoints to admin roles.
+
+## Verification Is a Completion Gate
+
+Before treating an agent-driven implementation as complete, run SwallowKit
+verification:
+
+```bash
+{{runCmd}} swallowkit machine verify project
+```
+
+or the equivalent MCP operation.
+
+Verification covers SwallowKit structural correctness, drift, type correctness,
+and configured project checks.
+
+When verification fails, use the structured failure explanation:
+
+```bash
+{{runCmd}} swallowkit machine explain failure
+```
+
+or its MCP equivalent, then repair the appropriate source and verify again.
+
+Use the `swallowkit-verify-repair` Agent Skill or runbook when applicable.
+
+SwallowKit verification answers:
+
+> Is the SwallowKit project mechanically and structurally valid?
+
+A semantic code review answers different questions:
+
+> Is this implementation well designed?
+> Does it satisfy the specification and user intent?
+
+Therefore, perform SwallowKit verification before treating semantic code review
+as the final quality gate.
+
+## Human Approval Gates
+
+A machine operation may return terminal states such as:
+
+- `complete`
+- `in-progress`
+- `blocked`
+- `requires-human`
+- `failed`
+
+Follow `nextActions`.
+
+When the status is `requires-human`, stop and request the required human
+decision.
+
+Do not reinterpret `requires-human` as an error to work around.
+
+Azure provisioning is a human-approved operation.
+
+Use the `swallowkit-provision` Agent Skill or runbook and never bypass its
+approval gate. A broad request to deploy does not itself grant the explicit
+approval required by that workflow.
+
+## SwallowKit Agent Skills and Runbooks
+
+SwallowKit installs task-specific Agent Skills under:
+
+```text
+.github/skills/
+```
+
+Current workflows include:
+
+- `swallowkit-add-model`
+- `swallowkit-modify-model`
+- `swallowkit-add-auth`
+- `swallowkit-verify-repair`
+- `swallowkit-provision`
+
+Equivalent agent-agnostic runbooks are available under:
+
+```text
+.swallowkit/workflows/
+```
+
+If the runtime supports Agent Skills, use the relevant Skill when the task
+matches. If it does not, read the corresponding runbook.
+
+These task-specific instructions supplement this `AGENTS.md`; they do not
+replace the always-on project contract.
+
+## Architecture
+
+This is a full-stack application deployed on Azure with a TypeScript
+frontend/BFF and an Azure Functions backend in {{backendLanguageLabel}}.
+
+```text
+Frontend (React / Next.js App Router)
+  ↓
+BFF (Next.js API Routes)
+  ↓
+Azure Functions
+  ↓
+Azure Cosmos DB
+```
+
+### Core architecture rules
+
+1. Next.js API routes are a BFF/proxy layer. Do not place application business
+   logic or direct database access there.
+2. Zod schemas under `shared/models/` are the application model source of truth.
+3. Do not duplicate model definitions across layers.
+4. Azure Functions own backend business logic and data access.
+5. SwallowKit-generated artifacts must be changed through their source of truth
+   and deterministic generation workflow, not by hand.
+6. Infrastructure is managed as code with Bicep. Respect SwallowKit ownership
+   markers and boundaries.
+7. Production access to Azure resources must follow the generated security
+   architecture; do not introduce hard-coded credentials or connection strings.
+
+### Backend-specific rules
+
+{{backendRules}}
+
+The backend owns `id`, `createdAt`, and `updatedAt`; never trust client-sent
+values for these fields.
+
+## Project Structure
+
+```text
+{{projectName}}/
+├── app/                    # Next.js App Router
+│   ├── api/                # BFF routes
+│   └── {model}/            # generated/custom UI
+├── functions/              # Azure Functions backend
+{{functionsStructureLine}}
+├── shared/
+│   ├── models/             # Zod source-of-truth models
+│   └── index.ts
+├── lib/
+│   └── api/
+├── components/
+├── infra/                  # Bicep infrastructure
+├── .swallowkit/            # SwallowKit project metadata and runbooks
+├── .github/skills/         # SwallowKit Agent Skills
+├── .mcp.json               # project-scoped SwallowKit MCP bootstrap
+└── AGENTS.md
+```
+
+Inspect the current project rather than assuming every project has exactly the
+same generated structure.
+
+## Naming and Model Conventions
+
+- Model schema files use `shared/models/{kebab-case}.ts`.
+- The Zod schema constant and inferred TypeScript type use the same PascalCase
+  name: `export const Todo = z.object(...); export type Todo = z.infer<typeof Todo>`.
+- Re-export models from `shared/index.ts`.
+- `id` is a required `z.string()`; only `createdAt` / `updatedAt` are optional
+  backend-managed fields.
+- Models may declare `partitionKey`, `authPolicy`, `displayName`, and
+  `connectorConfig` as exported constants. Exact formats:
+  `{{runCmd}} swallowkit machine inspect capabilities` (modelDeclarations).
+- Cosmos DB containers use PascalCase plural names and default to `/id` as the
+  partition key unless the model declares another key, e.g.
+  `export const partitionKey = '/learnerId';` (the field must exist in the
+  schema).
+
+## Everyday Commands
+
+```bash
+{{pm}} install
+{{runCmd}} swallowkit dev
+{{pm}} run build
+{{pm}} run lint
+{{runCmd}} swallowkit machine verify project
+```
+
+Always invoke SwallowKit using the package-runner convention generated for this
+project. Do not arbitrarily mix package-manager invocation styles.
+
+## Final Rules
+
+Do not:
+
+- rely on remembered SwallowKit capabilities when current inspection can answer
+  the question
+- hand-edit deterministic SwallowKit-managed artifacts
+- bypass plan/apply safety checks
+- bypass human approval gates
+- duplicate model definitions across generated layers
+- move backend business logic into the BFF
+- decompose one end-to-end SwallowKit-generated feature into artificial
+  horizontal tickets solely because multiple generated layers exist
+- consider an implementation complete before SwallowKit verification succeeds
+
+Do:
+
+- inspect before making SwallowKit-dependent design assumptions
+- preserve external development-process workflows
+- use SwallowKit as the deterministic execution and verification layer
+- keep specifications focused on intent and observable behavior
+- prefer vertical, independently verifiable slices
+- verify before final semantic review
+
+Use `{{pm}}`, the package manager selected for this project. Do not introduce another package manager or lockfile. Use `{{runCmd}} swallowkit` for the project-local CLI. The MCP launcher intentionally resolves `latest` independently.

package/src/core/project/agent-templates/CLAUDE.md

@@ -0,0 +1,31 @@
+# CLAUDE.md
+
+This is a **SwallowKit** project.
+
+Before discovery, requirements clarification, specification, planning, ticket
+decomposition, implementation, verification, or review, read and follow the
+root `AGENTS.md`.
+
+SwallowKit must be considered before implementation, not only when generating
+code.
+
+Always-on rules:
+
+- Inspect the current project and SwallowKit capabilities before making
+  SwallowKit-dependent assumptions or asking questions the repository can answer.
+- Prefer `swallowkit_*` MCP tools.
+- Fall back to `{{runCmd}} swallowkit machine ...` when MCP is unavailable.
+- 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 all `requires-human` states and provisioning approval gates.
+- Run SwallowKit verification before considering implementation complete.
+
+Task-specific SwallowKit Agent Skills are available under `.github/skills/`.
+Equivalent agent-agnostic runbooks are available under
+`.swallowkit/workflows/`.
+
+The root `AGENTS.md` is the canonical project contract.