easysam-skill

EasySAM Skill

This skill provides opinionated workflows and syntax rules for building, validating, and deploying serverless applications using the EasySAM YAML-to-SAM generator.

Core Directives & Cardinal Rules

1. NEVER Edit template.yml Directly: template.yml (and template.yaml) is an ephemeral build artifact automatically generated by easysam generate and easysam deploy. Do NOT edit template.yml manually under any circumstances. All configuration changes must be made in resources.yaml, module-level easysam.yaml, or deploy-context.yaml.
2. FastAPI Lambdas MUST Be Greedy: Any Lambda function using FastAPI or similar routing frameworks must set greedy: true under integration:. FastAPI manages internal sub-path routing (/api/v1/items); non-greedy routes will cause API Gateway to return 404 for sub-routes.
3. Deployment Failure Circuit-Breaker: If easysam deploy or CloudFormation stack update gets stuck, fails, or enters a rollback loop 2 or more times: STOP attempting retries immediately. Do not run command loops. Output the exact failure details from CloudFormation logs and inform the user so they can intervene (e.g. manual console rollback, easysam delete --force, or fixing CloudFormation resource locks).
4. Do NOT Run Standalone prismarine generate-client: When using Prismarine in EasySAM, client code generation (prismarine_client.py) is automatically performed as an integrated step of easysam generate . and easysam deploy .. Do NOT execute separate prismarine generate-client shell commands.

Standard Project Hierarchy

EasySAM strictly enforces a modular "Module Pattern" for organizing AWS resources. Divide applications into feature or resource modules:

my-project/
├── resources.yaml            # Global configuration (prefix, tags, python, envvars) and module imports
├── deploy-context.yaml       # Environment overrides (dev, prod ARNs/VPCs)
├── .gitignore                # Excludes **/common/ and **/prismarine_clients/
├── sam/
│   └── thirdparty/
│       └── requirements.txt  # Runtime dependencies packaged into Lambda artifacts
├── pyproject.toml            # Dev dependencies (pytest, ruff, easysam)
├── backend/                  # Main module (imported by resources.yaml)
│   ├── database/             # Database resources module (DynamoDB or Prismarine schema)
│   │   ├── easysam.yaml
│   │   └── schema.prisma     # Prismarine schema (if using Prismarine ORM)
│   └── function/             # Compute resources module
│       └── my-function/
│           ├── easysam.yaml  # Local resource definition
│           └── index.py      # Lambda handler code
├── common/                   # Shared application logic & custom DynamoAccess helpers
│   ├── utils.py
│   └── dynamo_access.py      # Custom DynamoAccess helper (if not using Prismarine)
└── tests/                    # Unit & integration test suite (pytest)
    └── test_myapp.py

Key Architectural & Git Conventions

• Modular Imports: Root resources.yaml must list sub-modules under import: (e.g., import: [backend]).
• Git Configuration: Every .gitignore (or root .gitignore) must exclude:
  • **/common/ (synced shared code modules)
  • **/prismarine_clients/ (auto-generated Prismarine ORM clients)
• Dependency Management:
  • Place Lambda runtime packages in sam/thirdparty/requirements.txt.
  • Keep project dependencies empty in pyproject.toml ([project] dependencies = []) and place development tools under [dependency-groups] dev.

Data Access Guidance: Prismarine vs Custom DynamoAccess

When building DynamoDB-backed applications in EasySAM, choose one of two supported data access patterns:

1. Prismarine (Prisma for DynamoDB):
   • Use Case: Schema-driven ORM with type-safe models, auto-generated Pydantic models, and structured queries.
   • Setup: Define models in common/<package>/models.py and configure prismarine: in resources.yaml. EasySAM automatically generates prismarine_client.py during easysam generate . or easysam deploy ..
2. Custom DynamoAccess (boto3 Helper):
   • Use Case: Lightweight, zero-dependency, low-latency DynamoDB access using direct boto3 queries.
   • Setup: Define a DynamoAccess class in common/dynamo_access.py wrapping boto3.resource('dynamodb') table operations (get_item, put_item, query, update_item).

Core Developer Workflows

1. Scaffolding a New Application

1. Run uv run easysam init to initialize project baseline.
2. Structure modules by boundary (e.g., backend/database/, backend/orders/).
3. Define global settings in resources.yaml (set prefix, tags, python, import).
4. Ensure .gitignore ignores **/common/ and **/prismarine_clients/.

2. Adding a Resource (Implement-Validate-Test Cycle)

1. Add local resource definitions in the target module's easysam.yaml.
2. Schema Validation Gate: Run uv run easysam --environment dev inspect schema . to validate YAML schema.
3. Write minimal Lambda handler code alongside the module's easysam.yaml.
4. Write unit tests in tests/ using pytest.

3. Deployment Pipeline & Safety

1. Cloud Verification Gate: Run uv run easysam --environment dev --aws-profile <profile> inspect cloud . to verify external ARNs and roles.
2. Template Preview: Run uv run easysam --environment dev generate . to inspect generated templates and generate Prismarine clients automatically. (Do NOT edit template.yml directly or run standalone prismarine generate-client).
3. Deploy: Run uv run easysam --environment dev --aws-profile <profile> deploy ..
4. Stuck Deployment Safety: If deployment fails or hangs 2+ times, STOP retrying and report CloudFormation stack status to the user.

EasySAM YAML Syntax Rules

1. Resource References

• Refer to local DynamoDB tables and S3 buckets by bare name strings (MyTable, my-bucket). Do NOT use !Ref.

2. Environment Variables

• envvars MUST be defined under resources:, NOT as a sibling of resources: under lambda:.
• SSM Parameters: Use {{resolve:ssm:/path/to/param}}. Do NOT use !Param.

3. HTTP Integrations & Greedy Routes

• Use integration: (not api:). Ensure each HTTP Lambda has a unique path prefix.
• FastAPI / Framework Lambdas: Always specify greedy: true.

lambda:
  name: api-handler
  integration:
    path: /api/v1
    greedy: true      # Mandatory for FastAPI to handle sub-paths
    open: true

Reference Material

• Examples Index: See references/examples.md for a complete mapping of all 18 example projects under example/ in the easysam repository.
• Resource Recipes & Patterns: See references/patterns.md for full YAML recipes across all 14 supported resource types (FastAPI greedy routes, OpenSearch Serverless, Lambda Function URLs, Kinesis Streams, Custom Layers, Custom Authorizers, IoT MQTT, Prismarine vs DynamoAccess, DynamoDB, S3, SQS, SNS, Poller).
• Troubleshooting: See references/troubleshooting.md for schema, cloud, stack lock, and template resolution error fixes.
• CI/CD Pipeline: Use assets/publish.yml for GitHub Actions OIDC deployment.