Makefile

Stoobly Scaffold Makefile - Questions & Answers

After scaffolding your app and services, you can use the Makefile located at .stoobly/services/.Makefile to manage your workflows with simple make commands.

---

Getting Started with Make Commands

Q: Where is the Makefile located after scaffolding?

A: The Makefile is automatically created at .stoobly/services/.Makefile in your application directory after scaffolding.

Example:

cd /path/to/your-app
ls .stoobly/services/.Makefile

Q: How do I run make commands from my project root?

A: Use the -f flag to specify the Makefile path, or create a symlink in your project root.

Example:

# Option 1: Specify the Makefile path
make -f .stoobly/services/.Makefile record

# Option 2: Create a symlink (one-time setup)
ln -s .stoobly/services/.Makefile Makefile
make record

---

Recording Workflow

Q: How do I start a recording workflow?

A: Use make record to start the recording workflow, which sets up the proxy to capture HTTP requests.

Example:

make -f .stoobly/services/.Makefile record

Q: How do I stop a recording workflow?

A: Use make record/down to stop and clean up the recording workflow.

Example:

make -f .stoobly/services/.Makefile record/down

Q: How do I view logs from the recording workflow?

A: Use make record/logs to display logs from all services in the recording workflow.

Example:

make -f .stoobly/services/.Makefile record/logs

Q: How do I list services in the recording workflow?

A: Use make record/services to display all configured services for the recording workflow.

Example:

make -f .stoobly/services/.Makefile record/services

Q: How do I view the recorded requests report?

A: Use make record/report to display a list of all intercepted and recorded requests.

Example:

make -f .stoobly/services/.Makefile record/report

---

Mock Workflow

Q: How do I start a mock workflow?

A: Use make mock to start the mock workflow, which serves mocked responses based on recorded data.

Example:

make -f .stoobly/services/.Makefile mock

Q: How do I stop a mock workflow?

A: Use make mock/down to stop and clean up the mock workflow.

Example:

make -f .stoobly/services/.Makefile mock/down

Q: How do I view logs from the mock workflow?

A: Use make mock/logs to display logs from all services in the mock workflow.

Example:

make -f .stoobly/services/.Makefile mock/logs

Q: How do I list services in the mock workflow?

A: Use make mock/services to display all configured services for the mock workflow.

Example:

make -f .stoobly/services/.Makefile mock/services

Q: How do I view the mock requests report?

A: Use make mock/report to display a list of all mocked requests.

Example:

make -f .stoobly/services/.Makefile mock/report

---

Test Workflow

Q: How do I start a test workflow?

A: Use make test to start the test workflow, which runs automated tests against your services.

Example:

make -f .stoobly/services/.Makefile test

Q: How do I stop a test workflow?

A: Use make test/down to stop and clean up the test workflow.

Example:

make -f .stoobly/services/.Makefile test/down

Q: How do I view logs from the test workflow?

A: Use make test/logs to display logs from all services in the test workflow.

Example:

make -f .stoobly/services/.Makefile test/logs

Q: How do I list services in the test workflow?

A: Use make test/services to display all configured services for the test workflow.

Example:

make -f .stoobly/services/.Makefile test/services

Q: How do I view the test requests report?

A: Use make test/report to display a list of all test requests and results.

Example:

make -f .stoobly/services/.Makefile test/report

---

Scenario Management

Q: How do I create a scenario using make?

A: Use make scenario/create with the name variable to create a new scenario.

Example:

make -f .stoobly/services/.Makefile scenario/create name="User Login Flow"

Q: How do I list all scenarios using make?

A: Use make scenario/list to display all available scenarios.

Example:

make -f .stoobly/services/.Makefile scenario/list

Q: How do I delete a scenario using make?

A: Use make scenario/delete with the key variable to delete a specific scenario.

Example:

make -f .stoobly/services/.Makefile scenario/delete key=abc123-scenario-key

Q: How do I snapshot a scenario using make?

A: Use make scenario/snapshot with the key variable to create committable files for a scenario.

Example:

make -f .stoobly/services/.Makefile scenario/snapshot key=abc123-scenario-key

Q: How do I reset a scenario to its snapshot state?

A: Use make scenario/reset with the key variable to restore a scenario from its snapshot.

Example:

make -f .stoobly/services/.Makefile scenario/reset key=abc123-scenario-key

Q: How do I overwrite a scenario using make?

A: Use make scenario/overwrite with the key variable to overwrite an existing scenario.

Example:

make -f .stoobly/services/.Makefile scenario/overwrite key=abc123-scenario-key

---

Certificate Management

Q: How do I install the CA certificate using make?

A: The CA certificate is automatically installed when you start a workflow, but you can manually trigger it with make ca-cert/install.

Example:

make -f .stoobly/services/.Makefile ca-cert/install

Q: How do I skip the CA certificate installation prompt?

A: Set the STOOBLY_CA_CERTS_INSTALL_CONFIRM environment variable to y before running the workflow.

Example:

export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y
make -f .stoobly/services/.Makefile record

---

Hostname Management

Q: How do I skip the hostname installation prompt?

A: Set the STOOBLY_HOSTNAME_INSTALL_CONFIRM environment variable to y to automatically confirm hostname installation.

Example:

export STOOBLY_HOSTNAME_INSTALL_CONFIRM=y
make -f .stoobly/services/.Makefile record

Q: How do I prevent hostname installation?

A: Set the STOOBLY_HOSTNAME_INSTALL_CONFIRM environment variable to n to skip hostname installation.

Example:

export STOOBLY_HOSTNAME_INSTALL_CONFIRM=n
make -f .stoobly/services/.Makefile mock

---

Intercept Management

Q: How do I enable intercept mode using make?

A: Use make intercept/enable with an optional scenario_key to enable request interception.

Example:

make -f .stoobly/services/.Makefile intercept/enable scenario_key=abc123

Q: How do I disable intercept mode using make?

A: Use make intercept/disable to turn off request interception.

Example:

make -f .stoobly/services/.Makefile intercept/disable

---

Environment Variables & Configuration

Q: How do I specify a custom application directory?

A: Set the STOOBLY_APP_DIR environment variable to point to your application directory.

Example:

export STOOBLY_APP_DIR=/path/to/my-app
make -f .stoobly/services/.Makefile record

Q: How do I use a custom .env file with workflows?

A: Set the STOOBLY_DOTENV_FILE environment variable to specify your .env file path.

Example:

export STOOBLY_DOTENV_FILE=/path/to/custom.env
make -f .stoobly/services/.Makefile mock

Q: How do I specify custom CA certificate directory?

A: Set the STOOBLY_CA_CERTS_DIR environment variable to your custom certificate directory.

Example:

export STOOBLY_CA_CERTS_DIR=/path/to/certs
make -f .stoobly/services/.Makefile record

Q: How do I pass additional service options to workflows?

A: Set the STOOBLY_WORKFLOW_SERVICE_OPTIONS environment variable with your custom options.

Example:

export STOOBLY_WORKFLOW_SERVICE_OPTIONS="--service api --service database"
make -f .stoobly/services/.Makefile record

Q: How do I specify a custom context directory?

A: Set the STOOBLY_CONTEXT_DIR environment variable to your desired context directory.

Example:

export STOOBLY_CONTEXT_DIR=/path/to/context
make -f .stoobly/services/.Makefile test

---

Advanced Workflow Options

Q: How do I pass additional options to workflow up commands?

A: Use the options variable to pass extra options to the workflow.

Example:

make -f .stoobly/services/.Makefile record options="--detach"

Q: How do I run a workflow with a custom namespace?

A: Use the namespace variable to specify a custom workflow namespace.

Example:

make -f .stoobly/services/.Makefile record namespace=my-custom-namespace

Q: How do I filter services when starting a workflow?

A: Set the STOOBLY_WORKFLOW_SERVICE_OPTIONS environment variable to specify which services to include.

Example:

export STOOBLY_WORKFLOW_SERVICE_OPTIONS="--service api --service frontend"
make -f .stoobly/services/.Makefile mock

---

Combining Multiple Environment Variables

Q: How do I run a fully automated workflow without any prompts?

A: Set both hostname and CA certificate confirmation environment variables before running the workflow.

Example:

export STOOBLY_HOSTNAME_INSTALL_CONFIRM=y
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y
make -f .stoobly/services/.Makefile record

Q: How do I run a workflow with custom directories and environment?

A: Set multiple environment variables to customize all aspects of the workflow.

Example:

export STOOBLY_APP_DIR=/path/to/app
export STOOBLY_DOTENV_FILE=/path/to/.env.production
export STOOBLY_WORKFLOW_SERVICE_OPTIONS="--service api"
make -f .stoobly/services/.Makefile mock

---

Troubleshooting

Q: How do I check if stoobly-agent is installed?

A: The Makefile automatically checks and installs stoobly-agent via pipx if needed. You can manually trigger this with make stoobly/install.

Example:

make -f .stoobly/services/.Makefile stoobly/install

Q: How do I verify Python version compatibility?

A: Use make python/validate to check if you have a compatible Python version (3.10, 3.11, or 3.12).

Example:

make -f .stoobly/services/.Makefile python/validate

Q: What do I do if pipx is not installed?

A: The Makefile automatically installs pipx if it's missing. You can manually trigger this with make pipx/install.

Example:

make -f .stoobly/services/.Makefile pipx/install

Q: How do I view what services are configured?

A: Use the workflow-specific services command to list all configured services.

Example:

make -f .stoobly/services/.Makefile record/services
make -f .stoobly/services/.Makefile mock/services
make -f .stoobly/services/.Makefile test/services

---

CI/CD Integration

Q: How do I use the Makefile in CI/CD pipelines?

A: Set all confirmation environment variables to avoid prompts and run the desired workflow commands.

Example:

#!/bin/bash
# CI/CD script example
export STOOBLY_HOSTNAME_INSTALL_CONFIRM=y
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y
export STOOBLY_APP_DIR=$PWD

# Start test workflow
make -f .stoobly/services/.Makefile test

# Run your tests here
# ...

# Clean up
make -f .stoobly/services/.Makefile test/down

Q: How do I run workflows in Docker containers?

A: The Makefile automatically handles Docker-based workflows. Ensure Docker is running and accessible.

Example:

# Verify Docker is running
docker ps

# Start workflow (automatically uses Docker)
make -f .stoobly/services/.Makefile record

---

Quick Reference

Q: What are the most common make commands I'll use?

A: Here's a quick reference of the most frequently used commands:

Example:

# Start workflows
make -f .stoobly/services/.Makefile record    # Start recording
make -f .stoobly/services/.Makefile mock      # Start mocking
make -f .stoobly/services/.Makefile test      # Start testing

# Stop workflows
make -f .stoobly/services/.Makefile record/down
make -f .stoobly/services/.Makefile mock/down
make -f .stoobly/services/.Makefile test/down

# View logs
make -f .stoobly/services/.Makefile record/logs
make -f .stoobly/services/.Makefile mock/logs
make -f .stoobly/services/.Makefile test/logs

# Manage scenarios
make -f .stoobly/services/.Makefile scenario/list
make -f .stoobly/services/.Makefile scenario/create name="My Scenario"
make -f .stoobly/services/.Makefile scenario/snapshot key=abc123

# View reports
make -f .stoobly/services/.Makefile record/report
make -f .stoobly/services/.Makefile mock/report

Q: How do I create an alias for easier make command usage?

A: Add an alias to your shell configuration file for convenience.

Example:

# Add to ~/.bashrc or ~/.zshrc
alias smake='make -f .stoobly/services/.Makefile'

# Then use it like:
smake record
smake mock/down
smake scenario/list

This comprehensive Q&A guide covers all the make commands available in the Stoobly scaffold Makefile, providing users with clear examples and use cases for each command.