sofia-cli 0.1.2 → 0.1.4

package/README.md

@@ -69,22 +69,34 @@ sofIA uses [Model Context Protocol](https://modelcontextprotocol.io/) servers to
 ```bash
 # Prerequisites: Node.js >= 20, a GitHub Copilot subscription
 
-# Clone & install
-git clone https://github.com/jmservera/sofia-cli.git
-cd sofia-cli
-npm install
+# Install globally from npm
+npm install -g sofia-cli
+
+# Or run directly with npx (no install required)
+npx sofia-cli workshop
 
 # Start an interactive workshop
-npm run start -- workshop
+sofia workshop
 
 # Check session status
-npm run start -- status
+sofia status
 
 # Generate a PoC from a completed session
-npm run start -- dev --session <id>
+sofia dev --session <id>
 
 # Export workshop artifacts
-npm run start -- export --session <id>
+sofia export --session <id>
+```
+
+### Development Setup
+
+If you want to contribute or run from source:
+
+```bash
+git clone https://github.com/jmservera/sofia-cli.git
+cd sofia-cli
+npm install
+npm run start -- workshop
 ```
 
 ## CLI Commands
@@ -111,24 +123,28 @@ infra/                # Azure AI Foundry IaC (Bicep + deployment scripts)
 src/
 ├── cli/              # Command handlers (workshop, dev, status, export)
 ├── develop/          # PoC generation & Ralph loop
-│   ├── ralphLoop.ts  # Autonomous iteration orchestrator
-│   ├── pocScaffolder.ts  # Project scaffolding
-│   ├── codeGenerator.ts  # LLM-driven code generation
-│   ├── testRunner.ts     # Test execution & result parsing
+│   ├── ralphLoop.ts          # Autonomous iteration orchestrator
+│   ├── dynamicScaffolder.ts  # LLM-based project scaffolding
+│   ├── codeGenerator.ts      # LLM-driven code generation
+│   ├── testRunner.ts         # Test execution & result parsing
+│   ├── checkpointState.ts    # Resume/checkpoint detection
 │   └── ...
 ├── loop/             # Multi-turn conversation orchestrator
 ├── phases/           # Phase handlers & JSON extractors
 ├── prompts/          # Versioned prompt templates
 ├── sessions/         # Session persistence & export
-├── mcp/              # MCP server connection manager
+├── mcp/              # MCP server connection manager & transports
 ├── shared/           # Schemas, events, error classification
 │   └── schemas/      # Zod schemas for session state
 └── vendor/           # Re-exports of external packages
 
 specs/
-├── 001-cli-workshop-rebuild/   # Workshop phases spec & tasks
-├── 002-poc-generation/         # Develop phase spec & tasks
-└── 003-next-spec-gaps.md       # Outstanding gaps for next feature
+├── 001-cli-workshop-rebuild/       # Workshop phases orchestration
+├── 002-poc-generation/             # Develop phase & Ralph loop
+├── 003-mcp-transport-integration/  # Real MCP server connections
+├── 004-dev-resume-hardening/       # Checkpoint, resume, --force
+├── 005-ai-search-deploy/           # Azure AI Foundry infrastructure
+└── 006-workshop-extraction-fixes/  # Extraction, wiring, context mgmt
 
 docs/                 # User-facing documentation
 tests/
@@ -183,10 +199,16 @@ See [.github/copilot-instructions.md](.github/copilot-instructions.md) for detai
 
 ## Current Status
 
-- **Feature 001** (Workshop CLI): Discover → Ideate → Design → Select → Plan — **implemented and tested**
-- **Feature 002** (PoC Generation): Develop phase with Ralph loop — **implemented and tested** (MCP integrations are simulated; see [specs/003-next-spec-gaps.md](specs/003-next-spec-gaps.md))
-- **Feature 003** (MCP Integration): Real MCP tool invocation, resume/checkpoint, additional templates — **planned**
-- **Feature 005** (AI Search Deploy): Azure AI Foundry infrastructure deployment + SDK-based web search integration — **implemented and tested**
+All six features have been implemented and tested:
+
+| Feature | Title                                                           | Description                                                            | Status          |
+| ------- | --------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------- |
+| 001     | [Workshop Rebuild](specs/001-cli-workshop-rebuild/spec.md)      | 5-phase orchestration (Discover → Plan), session persistence, export   | **Implemented** |
+| 002     | [PoC Generation](specs/002-poc-generation/spec.md)              | Develop phase with Ralph loop, LLM-based dynamic scaffolding           | **Implemented** |
+| 003     | [MCP Transport](specs/003-mcp-transport-integration/spec.md)    | Real MCP tool invocation (GitHub, Context7, Azure, web search, WorkIQ) | **Implemented** |
+| 004     | [Dev Hardening](specs/004-dev-resume-hardening/spec.md)         | Checkpoint/resume, `--force` flag, template registry, test coverage    | **Implemented** |
+| 005     | [Search Deployment](specs/005-ai-search-deploy/spec.md)         | Azure AI Foundry Bicep infrastructure with one-command deploy/teardown | **Implemented** |
+| 006     | [Extraction Fixes](specs/006-workshop-extraction-fixes/spec.md) | Fallback extraction, MCP wiring per phase, context window management   | **Implemented** |
 
 ## Web Search Setup
 

package/dist/infra/deploy.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────────────────────
+# deploy.sh — One-command Azure AI Foundry deployment for sofIA
+#
+# Provisions:
+#   - Resource group (auto-created)
+#   - AI Services account with Foundry project
+#   - Model deployment (gpt-4.1-mini by default)
+#   - Agent Service capability hosts
+#
+# Usage:
+#   ./infra/deploy.sh --resource-group <name> [options]
+#
+# Exit codes:
+#   0 — Deployment succeeded
+#   1 — Prerequisite check failed
+#   2 — Deployment failed
+# ──────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ── Defaults ──────────────────────────────────────────────────────────────────
+
+SUBSCRIPTION=""
+RESOURCE_GROUP=""
+LOCATION="swedencentral"
+ACCOUNT_NAME="sofia-foundry"
+MODEL="gpt-4.1-mini"
+
+# ── Parameter parsing ─────────────────────────────────────────────────────────
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+Required:
+  -g, --resource-group <name>   Resource group name (created if missing)
+
+Optional:
+  -s, --subscription <id>       Azure subscription ID (default: current az CLI subscription)
+  -l, --location <region>       Azure region (default: swedencentral)
+  -n, --account-name <name>     Foundry account name (default: sofia-foundry)
+  -m, --model <name>            Model deployment name (default: gpt-4.1-mini)
+  -h, --help                    Show this help message
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -s|--subscription)
+      SUBSCRIPTION="$2"; shift 2 ;;
+    -g|--resource-group)
+      RESOURCE_GROUP="$2"; shift 2 ;;
+    -l|--location)
+      LOCATION="$2"; shift 2 ;;
+    -n|--account-name)
+      ACCOUNT_NAME="$2"; shift 2 ;;
+    -m|--model)
+      MODEL="$2"; shift 2 ;;
+    -h|--help)
+      usage; exit 0 ;;
+    *)
+      echo "❌ Unknown option: $1" >&2
+      usage >&2
+      exit 1 ;;
+  esac
+done
+
+# ── Validate required parameters ─────────────────────────────────────────────
+
+if [[ -z "$RESOURCE_GROUP" ]]; then
+  echo "❌ Missing required parameter: --resource-group (-g)" >&2
+  usage >&2
+  exit 1
+fi
+
+# ── Prerequisite checks ──────────────────────────────────────────────────────
+
+echo "🔍 Checking prerequisites..."
+
+# Check az CLI is installed
+if ! command -v az &>/dev/null; then
+  echo "❌ Azure CLI (az) is not installed." >&2
+  echo "   Install: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli" >&2
+  exit 1
+fi
+
+# Check user is logged in
+if ! az account show &>/dev/null; then
+  echo "❌ Not logged in to Azure. Run 'az login' first." >&2
+  exit 1
+fi
+
+# Optionally set subscription
+if [[ -n "$SUBSCRIPTION" ]]; then
+  echo "📋 Setting subscription to: $SUBSCRIPTION"
+  if ! az account set --subscription "$SUBSCRIPTION" 2>/dev/null; then
+    echo "❌ Could not set subscription '$SUBSCRIPTION'." >&2
+    echo "   Check the subscription ID and your permissions." >&2
+    exit 1
+  fi
+fi
+
+echo "✅ Prerequisites passed"
+
+# ── Resolve current user's principal (object) ID for RBAC ─────────────────────
+
+echo "🔑 Resolving current user's principal ID..."
+USER_PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv 2>/dev/null || true)
+if [[ -z "$USER_PRINCIPAL_ID" ]]; then
+  echo "⚠️  Could not resolve user principal ID. Role assignment will be skipped." >&2
+  echo "   You may need to manually assign the 'Azure AI Developer' role." >&2
+else
+  echo "   Principal ID: $USER_PRINCIPAL_ID"
+fi
+
+# ── Deploy ────────────────────────────────────────────────────────────────────
+
+echo ""
+echo "🚀 Deploying Azure AI Foundry infrastructure..."
+echo "   Resource Group: $RESOURCE_GROUP"
+echo "   Location:       $LOCATION"
+echo "   Account:        $ACCOUNT_NAME"
+echo "   Model:          $MODEL"
+echo ""
+
+DEPLOYMENT_NAME="sofia-foundry-$(date +%Y%m%d%H%M%S)"
+
+if ! az deployment sub create \
+  --location "$LOCATION" \
+  --name "$DEPLOYMENT_NAME" \
+  --template-file "$SCRIPT_DIR/main.bicep" \
+  --parameters "$SCRIPT_DIR/main.bicepparam" \
+  --parameters \
+    resourceGroupName="$RESOURCE_GROUP" \
+    location="$LOCATION" \
+    accountName="$ACCOUNT_NAME" \
+    modelDeploymentName="$MODEL" \
+    modelName="$MODEL" \
+    userPrincipalId="$USER_PRINCIPAL_ID" \
+  --output json; then
+  echo "" >&2
+  echo "❌ Deployment failed." >&2
+  echo "   Check the error above for details." >&2
+  echo "   Common issues:" >&2
+  echo "   - Insufficient permissions (need Owner or Contributor)" >&2
+  echo "   - Region doesn't support AI Foundry Agent Service" >&2
+  echo "   - Resource name conflict (try a different --account-name)" >&2
+  exit 2
+fi
+
+# ── Query outputs ─────────────────────────────────────────────────────────────
+
+PROJECT_ENDPOINT=$(az deployment sub show \
+  --name "$DEPLOYMENT_NAME" \
+  --query "properties.outputs.projectEndpoint.value" \
+  --output tsv 2>/dev/null || echo "")
+
+MODEL_DEPLOYMENT_NAME=$(az deployment sub show \
+  --name "$DEPLOYMENT_NAME" \
+  --query "properties.outputs.modelDeploymentName.value" \
+  --output tsv 2>/dev/null || echo "$MODEL")
+
+# ── Write .env file ───────────────────────────────────────────────────────────
+
+ENV_FILE="$SCRIPT_DIR/../.env"
+
+# Helper: set or update a KEY=VALUE in the .env file
+set_env_var() {
+  local key="$1" value="$2"
+  if [[ -f "$ENV_FILE" ]] && grep -q "^${key}=" "$ENV_FILE"; then
+    # Update existing entry (portable sed -i)
+    sed -i "s|^${key}=.*|${key}=\"${value}\"|" "$ENV_FILE"
+  else
+    echo "${key}=\"${value}\"" >> "$ENV_FILE"
+  fi
+}
+
+set_env_var "FOUNDRY_PROJECT_ENDPOINT" "$PROJECT_ENDPOINT"
+set_env_var "FOUNDRY_MODEL_DEPLOYMENT_NAME" "$MODEL_DEPLOYMENT_NAME"
+
+# ── Output ────────────────────────────────────────────────────────────────────
+
+echo ""
+echo "✅ Deployment complete!"
+echo ""
+echo "Environment variables written to $(realpath "$ENV_FILE"):"
+echo ""
+echo "  FOUNDRY_PROJECT_ENDPOINT=\"$PROJECT_ENDPOINT\""
+echo "  FOUNDRY_MODEL_DEPLOYMENT_NAME=\"$MODEL_DEPLOYMENT_NAME\""
+echo ""
+echo "To tear down: ./infra/teardown.sh --resource-group $RESOURCE_GROUP"

package/dist/infra/gather-env.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────────────────────
+# gather-env.sh — Fetch environment values from an existing Azure AI Foundry
+#                 resource group without redeploying.
+#
+# Queries the AI Services account and project already provisioned by deploy.sh,
+# then writes (or updates) the .env file with the same variables.
+#
+# Usage:
+#   ./infra/gather-env.sh --resource-group <name> [options]
+#
+# Exit codes:
+#   0 — Values gathered and written successfully
+#   1 — Prerequisite / parameter check failed
+#   2 — Resource query failed
+# ──────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ── Defaults ──────────────────────────────────────────────────────────────────
+
+SUBSCRIPTION=""
+RESOURCE_GROUP=""
+ACCOUNT_NAME="sofia-foundry"
+MODEL=""
+
+# ── Parameter parsing ─────────────────────────────────────────────────────────
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+Required:
+  -g, --resource-group <name>   Resource group containing the Foundry resources
+
+Optional:
+  -s, --subscription <id>       Azure subscription ID (default: current az CLI subscription)
+  -n, --account-name <name>     AI Services account name (default: sofia-foundry)
+  -m, --model <name>            Override model deployment name (default: auto-detected)
+  -h, --help                    Show this help message
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -s|--subscription)
+      SUBSCRIPTION="$2"; shift 2 ;;
+    -g|--resource-group)
+      RESOURCE_GROUP="$2"; shift 2 ;;
+    -n|--account-name)
+      ACCOUNT_NAME="$2"; shift 2 ;;
+    -m|--model)
+      MODEL="$2"; shift 2 ;;
+    -h|--help)
+      usage; exit 0 ;;
+    *)
+      echo "❌ Unknown option: $1" >&2
+      usage >&2
+      exit 1 ;;
+  esac
+done
+
+# ── Validate required parameters ─────────────────────────────────────────────
+
+if [[ -z "$RESOURCE_GROUP" ]]; then
+  echo "❌ Missing required parameter: --resource-group (-g)" >&2
+  usage >&2
+  exit 1
+fi
+
+# ── Prerequisite checks ──────────────────────────────────────────────────────
+
+echo "🔍 Checking prerequisites..."
+
+if ! command -v az &>/dev/null; then
+  echo "❌ Azure CLI (az) is not installed." >&2
+  echo "   Install: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli" >&2
+  exit 1
+fi
+
+if ! az account show &>/dev/null; then
+  echo "❌ Not logged in to Azure. Run 'az login' first." >&2
+  exit 1
+fi
+
+if [[ -n "$SUBSCRIPTION" ]]; then
+  echo "📋 Setting subscription to: $SUBSCRIPTION"
+  if ! az account set --subscription "$SUBSCRIPTION" 2>/dev/null; then
+    echo "❌ Could not set subscription '$SUBSCRIPTION'." >&2
+    exit 1
+  fi
+fi
+
+echo "✅ Prerequisites passed"
+
+# ── Verify resource group exists ──────────────────────────────────────────────
+
+echo ""
+echo "🔍 Verifying resource group: $RESOURCE_GROUP"
+
+if ! az group show --name "$RESOURCE_GROUP" &>/dev/null; then
+  echo "❌ Resource group '$RESOURCE_GROUP' not found." >&2
+  echo "   Run deploy.sh first to create the infrastructure." >&2
+  exit 2
+fi
+
+# ── Find the AI Services account ─────────────────────────────────────────────
+
+echo "🔍 Looking up AI Services account: $ACCOUNT_NAME"
+
+if ! az cognitiveservices account show \
+       --resource-group "$RESOURCE_GROUP" \
+       --name "$ACCOUNT_NAME" &>/dev/null; then
+  echo "⚠️  Account '$ACCOUNT_NAME' not found. Searching for AI Services accounts in the resource group..."
+  ACCOUNT_NAME=$(az cognitiveservices account list \
+    --resource-group "$RESOURCE_GROUP" \
+    --query "[?kind=='AIServices'].name | [0]" \
+    --output tsv 2>/dev/null || true)
+
+  if [[ -z "$ACCOUNT_NAME" ]]; then
+    echo "❌ No AI Services account found in resource group '$RESOURCE_GROUP'." >&2
+    exit 2
+  fi
+  echo "   Found account: $ACCOUNT_NAME"
+fi
+
+# ── Find the project and its endpoint ────────────────────────────────────────
+
+echo "🔍 Looking up Foundry project..."
+
+PROJECT_ENDPOINT=$(az cognitiveservices account show \
+  --resource-group "$RESOURCE_GROUP" \
+  --name "$ACCOUNT_NAME" \
+  --query "properties.endpoints.\"AI Foundry API\"" \
+  --output tsv 2>/dev/null || true)
+
+# If the account-level endpoint isn't what we need, try querying the project
+if [[ -z "$PROJECT_ENDPOINT" ]]; then
+  # List projects under the account
+  PROJECT_NAME=$(az resource list \
+    --resource-group "$RESOURCE_GROUP" \
+    --resource-type "Microsoft.CognitiveServices/accounts/projects" \
+    --query "[0].name" \
+    --output tsv 2>/dev/null || true)
+
+  if [[ -n "$PROJECT_NAME" ]]; then
+    # The resource name is "account/project", extract just the project part
+    LOCAL_PROJECT="${PROJECT_NAME##*/}"
+    echo "   Found project: $LOCAL_PROJECT"
+
+    PROJECT_ENDPOINT=$(az rest \
+      --method GET \
+      --uri "https://management.azure.com/subscriptions/$(az account show --query id -o tsv)/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$ACCOUNT_NAME/projects/$LOCAL_PROJECT?api-version=2025-06-01" \
+      --query "properties.endpoints.\"AI Foundry API\"" \
+      --output tsv 2>/dev/null || true)
+  fi
+fi
+
+if [[ -z "$PROJECT_ENDPOINT" ]]; then
+  echo "❌ Could not determine the Foundry project endpoint." >&2
+  echo "   Ensure a project exists under account '$ACCOUNT_NAME'." >&2
+  exit 2
+fi
+
+echo "   Endpoint: $PROJECT_ENDPOINT"
+
+# ── Find the model deployment name ───────────────────────────────────────────
+
+if [[ -z "$MODEL" ]]; then
+  echo "🔍 Looking up model deployment..."
+  MODEL=$(az cognitiveservices account deployment list \
+    --resource-group "$RESOURCE_GROUP" \
+    --name "$ACCOUNT_NAME" \
+    --query "[0].name" \
+    --output tsv 2>/dev/null || true)
+
+  if [[ -z "$MODEL" ]]; then
+    echo "⚠️  No model deployment found. Using default: gpt-4.1-mini"
+    MODEL="gpt-4.1-mini"
+  fi
+fi
+
+echo "   Model deployment: $MODEL"
+
+# ── Write .env file ───────────────────────────────────────────────────────────
+
+ENV_FILE="$SCRIPT_DIR/../.env"
+
+set_env_var() {
+  local key="$1" value="$2"
+  if [[ -f "$ENV_FILE" ]] && grep -q "^${key}=" "$ENV_FILE"; then
+    sed -i "s|^${key}=.*|${key}=\"${value}\"|" "$ENV_FILE"
+  else
+    echo "${key}=\"${value}\"" >> "$ENV_FILE"
+  fi
+}
+
+set_env_var "FOUNDRY_PROJECT_ENDPOINT" "$PROJECT_ENDPOINT"
+set_env_var "FOUNDRY_MODEL_DEPLOYMENT_NAME" "$MODEL"
+
+# ── Output ────────────────────────────────────────────────────────────────────
+
+echo ""
+echo "✅ Environment values gathered successfully!"
+echo ""
+echo "Written to $(realpath "$ENV_FILE"):"
+echo ""
+echo "  FOUNDRY_PROJECT_ENDPOINT=\"$PROJECT_ENDPOINT\""
+echo "  FOUNDRY_MODEL_DEPLOYMENT_NAME=\"$MODEL\""
+echo ""