sofia-cli 0.1.1

package/infra/teardown.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────────────────────
+# teardown.sh — Remove Azure AI Foundry resources deployed by deploy.sh
+#
+# Deletes the specified resource group and all contained resources.
+# Clean exit (0) when the resource group doesn't exist.
+#
+# Usage:
+#   ./infra/teardown.sh --resource-group <name> [--yes]
+#
+# Exit codes:
+#   0 — Teardown succeeded or resource group doesn't exist
+#   1 — Prerequisite check failed
+#   2 — Deletion failed
+# ──────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# ── Defaults ──────────────────────────────────────────────────────────────────
+
+RESOURCE_GROUP=""
+AUTO_CONFIRM=false
+
+# ── Parameter parsing ─────────────────────────────────────────────────────────
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+Required:
+  -g, --resource-group <name>   Resource group to delete
+
+Optional:
+  --yes                         Skip confirmation prompt
+  -h, --help                    Show this help message
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -g|--resource-group)
+      RESOURCE_GROUP="$2"; shift 2 ;;
+    --yes)
+      AUTO_CONFIRM=true; shift ;;
+    -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
+
+echo "✅ Prerequisites passed"
+
+# ── Check if resource group exists ────────────────────────────────────────────
+
+echo ""
+echo "🔍 Checking resource group: $RESOURCE_GROUP"
+
+RG_EXISTS=$(az group exists --name "$RESOURCE_GROUP" 2>/dev/null || echo "false")
+
+if [[ "$RG_EXISTS" != "true" ]]; then
+  echo "ℹ️  Resource group '$RESOURCE_GROUP' does not exist. Nothing to delete."
+  exit 0
+fi
+
+# ── Confirm deletion ─────────────────────────────────────────────────────────
+
+if [[ "$AUTO_CONFIRM" != "true" ]]; then
+  echo ""
+  echo "⚠️  This will delete resource group '$RESOURCE_GROUP' and ALL its resources."
+  read -rp "Are you sure? (y/N): " confirm
+  if [[ "$confirm" != "y" && "$confirm" != "Y" ]]; then
+    echo "Cancelled."
+    exit 0
+  fi
+fi
+
+# ── Delete resource group ────────────────────────────────────────────────────
+
+echo ""
+echo "🗑️  Deleting resource group: $RESOURCE_GROUP"
+
+if ! az group delete --name "$RESOURCE_GROUP" --yes --no-wait; then
+  echo "" >&2
+  echo "❌ Failed to delete resource group '$RESOURCE_GROUP'." >&2
+  exit 2
+fi
+
+echo "✅ Resource group '$RESOURCE_GROUP' deletion initiated (non-blocking)."
+echo "   Resources will be fully removed within a few minutes."

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "sofia-cli",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "main": "dist/src/cli/index.js",
+  "bin": {
+    "sofia": "dist/src/cli/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && npm run build:assets",
+    "build:assets": "cp -r src/prompts/ dist/src/ && cp src/shared/data/cards.json dist/src/shared/data/",
+    "dev": "tsx watch src/cli/index.ts",
+    "start": "tsx src/cli/index.ts",
+    "clean": "rimraf dist coverage .nyc_output",
+    "lint": "eslint src tests",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
+    "test:live": "vitest run --config vitest.live.config.ts",
+    "sofiacli": "node --enable-source-maps dist/cli/index.js",
+    "sofia": "npm run sofiacli"
+  },
+  "dependencies": {
+    "@azure/ai-projects": "^2.0.0-beta.5",
+    "@azure/identity": "^4.13.0",
+    "@github/copilot-sdk": "^0.1.28",
+    "@inquirer/prompts": "^8.3.0",
+    "chalk": "^5.2.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^11.1.0",
+    "dotenv": "^17.3.1",
+    "marked": "^11.0.0",
+    "marked-terminal": "^6.2.0",
+    "ora": "^7.0.1",
+    "pino": "^8.17.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "@typescript-eslint/parser": "^7.1.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "node-pty": "^1.0.0",
+    "prettier": "^3.2.4",
+    "rimraf": "^5.0.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^4.0.18"
+  }
+}

package/specs/001-cli-workshop-rebuild/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: sofIA Unified Build-From-Scratch CLI
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-02-26
+**Feature**: [../spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs) — N/A: technology constraints (Copilot SDK, MCP, BXT) are non-negotiable project requirements, not implementation choices
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details) — N/A: technology constraints are non-negotiable project requirements, not implementation choices
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification — N/A: technology constraints are non-negotiable project requirements, not implementation choices
+
+## Notes
+
+- This spec intentionally includes technology constraints (Copilot SDK, MCP integrations, BXT framework) because they are explicit non-negotiables for the sofIA rebuild.
+- Clarifications captured in spec: repo-local persistence (`./.sofia/`), one JSON file per session, local scaffolding fallback for Develop when GitHub MCP is unavailable, default export to `./exports/<sessionId>/`, and persistence after every user turn.

package/specs/001-cli-workshop-rebuild/contracts/cli.md

@@ -0,0 +1,59 @@
+# Contract: CLI Surface
+
+This document defines the public CLI contract. Exact flags/subcommands may evolve, but breaking changes must be deliberate.
+
+## Binary
+
+- Name: `sofia`
+
+## Global options
+
+- `--help`
+- `--version`
+- `--session <id>`: target an existing session
+- `--new-session`: create a new session
+- `--non-interactive`: disallow prompts; fail with actionable error if input is missing
+- `--json`: emit machine-readable JSON **only** on stdout (no spinners/telemetry)
+- `--debug`: enable debug telemetry
+- `--log-file <path>`: write structured logs to file
+
+## Commands
+
+### 1) `sofia workshop`
+
+Starts or resumes the governed workshop flow.
+
+- Interactive by default (TTY).
+- In non-interactive mode, requires sufficient args or input file (defined in implementation).
+
+Outputs:
+- Human: streamed narrative + activity stream (stderr).
+- JSON mode: JSON events only on stdout.
+
+### 2) `sofia status`
+
+Displays session status and next expected action.
+
+Outputs:
+- Human: concise summary.
+- JSON: `{ sessionId, phase, status, updatedAt, nextAction }`.
+
+### 3) `sofia export`
+
+Exports artifacts for a session.
+
+- Default output: `./exports/<sessionId>/`
+- Output includes `summary.json` and phase markdown files.
+
+### 4) `sofia dev` (optional)
+
+Developer utilities (may be hidden) for local PoC scaffolding and diagnostics.
+
+## Error contract
+
+- Exit codes are stable and documented in implementation.
+- In JSON mode, errors are emitted as JSON objects with:
+  - `error.code`
+  - `error.message`
+  - `error.details?`
+

package/specs/001-cli-workshop-rebuild/contracts/export-summary-json.md

@@ -0,0 +1,23 @@
+# Contract: Export `summary.json`
+
+**Path**: `./exports/<sessionId>/summary.json`
+
+## Format
+
+- Encoding: UTF-8
+- JSON object
+
+## Minimum fields
+
+- `sessionId: string`
+- `exportedAt: string` (ISO-8601)
+- `phase: string`
+- `status: string`
+- `files: Array<{ path: string; type: string }>`
+- `highlights?: string[]`
+
+## Notes
+
+- `files[].path` is relative to the export directory.
+- Do not include secrets.
+

package/specs/001-cli-workshop-rebuild/contracts/session-json.md

@@ -0,0 +1,30 @@
+# Contract: Session JSON
+
+**Path**: `./.sofia/sessions/<sessionId>.json`
+
+## Format
+
+- Encoding: UTF-8
+- JSON object
+- Overwrite the file after each user turn (atomic write in implementation)
+
+## Minimum required fields
+
+- `sessionId: string`
+- `schemaVersion: string`
+- `createdAt: string` (ISO-8601)
+- `updatedAt: string` (ISO-8601)
+- `phase: string`
+- `status: string`
+- `artifacts.generatedFiles: array`
+
+## Compatibility
+
+- `schemaVersion` supports forward migration.
+- Unknown fields must be preserved when loading/saving.
+
+## Safety
+
+- Must not persist secrets/tokens.
+- Redact/omit any sensitive values from tool responses before writing.
+

package/specs/001-cli-workshop-rebuild/data-model.md

@@ -0,0 +1,210 @@
+# Data Model: sofIA CLI workshop rebuild
+
+**Feature**: ./spec.md
+**Research**: ./research.md
+**Date**: 2026-02-26
+
+This is a conceptual data model for persistence and exports. It is not an implementation.
+
+## Entities
+
+### 1) Session
+
+**Storage**: `./.sofia/sessions/<sessionId>.json`
+
+**Fields (minimum)**
+- `sessionId: string`
+- `createdAt: string` (ISO-8601)
+- `updatedAt: string` (ISO-8601)
+- `schemaVersion: string`
+- `phase: Phase`
+- `status: SessionStatus`
+- `participants: Participant[]`
+- `businessContext?: BusinessContext`
+- `topic?: TopicSelection`
+- `activities?: Activity[]`
+- `workflow?: WorkflowMap`
+- `cards?: CardSelection`
+- `ideas?: IdeaCard[]`
+- `evaluation?: IdeaEvaluation`
+- `selection?: SelectedIdea`
+- `plan?: ImplementationPlan`
+- `poc?: PocDevelopmentState`
+- `artifacts: ArtifactIndex`
+- `errors?: ErrorRecord[]`
+
+**Validation rules**
+- `sessionId` is stable across the session.
+- `updatedAt` is monotonically increasing.
+- `phase` must follow state machine (see below).
+- Every user turn persists the session to disk.
+
+### 2) Phase
+
+`Phase` is an enum representing the governed progression:
+- `Discover`
+- `Ideate`
+- `Design`
+- `Select`
+- `Plan`
+- `Develop`
+- `Complete`
+
+**Rule**: Phase changes require an explicit “Proceed?” decision gate in UX.
+
+### 3) SessionStatus
+
+- `Active`
+- `Paused`
+- `Completed`
+- `Errored`
+
+### 4) Participant
+
+- `id: string`
+- `displayName: string`
+- `role: "Facilitator" | "Attendee" | "Observer"`
+
+### 5) BusinessContext
+
+- `businessDescription: string`
+- `challenges: string[]`
+- `constraints?: string[]`
+- `successMetrics?: Metric[]`
+
+### 6) TopicSelection
+
+- `topicArea: string`
+- `scopeNotes?: string`
+
+### 7) WorkflowMap
+
+- `activities: WorkflowStep[]`
+- `edges: WorkflowEdge[]`
+
+`WorkflowStep`
+- `id: string`
+- `name: string`
+- `description?: string`
+- `metrics?: Metric[]` (e.g., hours/week, NSAT)
+
+`WorkflowEdge`
+- `fromStepId: string`
+- `toStepId: string`
+
+### 8) CardSelection
+
+- `selectedCards: EnvisioningCard[]`
+- `scores?: CardScore[]`
+
+`EnvisioningCard`
+- `id: string`
+- `title: string`
+- `category?: string`
+- `notes?: string`
+
+`CardScore`
+- `cardId: string`
+- `dimensions: Record<string, number>`
+
+### 9) IdeaCard
+
+- `id: string`
+- `title: string`
+- `description: string`
+- `workflowStepIds: string[]`
+- `aspirationalScope?: string`
+- `assumptions?: string[]`
+
+### 10) IdeaEvaluation
+
+- `ideas: IdeaEvaluationItem[]`
+- `method: "feasibility-value-matrix" | "custom"`
+
+`IdeaEvaluationItem`
+- `ideaId: string`
+- `feasibility: number` (normalized 0..1 or 1..5; decide in implementation)
+- `value: number`
+- `risks?: string[]`
+- `dataNeeded?: string[]`
+- `humanValue?: string[]`
+- `kpisInfluenced?: string[]`
+
+### 11) SelectedIdea
+
+- `ideaId: string`
+- `selectionRationale: string`
+- `confirmedByUser: boolean`
+- `confirmedAt?: string`
+
+### 12) ImplementationPlan
+
+- `milestones: Milestone[]`
+- `architectureNotes?: string`
+- `dependencies?: string[]`
+
+`Milestone`
+- `id: string`
+- `title: string`
+- `items: string[]`
+
+### 13) PocDevelopmentState
+
+- `repoPath?: string` (local path or external repo location, populated by Develop feature 002)
+- `iterations: PocIteration[]` (high-level record of Develop iterations; detailed behavior defined in feature 002)
+- `finalStatus?: "success" | "failed"`
+
+`PocIteration`
+- `iteration: number`
+- `startedAt: string`
+- `endedAt?: string`
+- `changesSummary?: string`
+- `testsRun?: string[]`
+
+### 14) Activity
+
+This replaces “LLM thoughts” with a compliant activity/telemetry stream.
+
+- `id: string`
+- `timestamp: string`
+- `kind: "phase" | "tool" | "io" | "warning" | "error" | "progress"`
+- `message: string`
+- `data?: Record<string, unknown>`
+
+### 15) ArtifactIndex
+
+- `exportDir?: string` (e.g., `./exports/<sessionId>/`)
+- `generatedFiles: GeneratedFile[]`
+
+`GeneratedFile`
+- `relativePath: string`
+- `type: "markdown" | "json" | "text"`
+- `createdAt: string`
+
+### 16) ErrorRecord
+
+- `timestamp: string`
+- `code: string`
+- `message: string`
+- `details?: Record<string, unknown>`
+
+## State machine
+
+Valid transitions:
+- `Discover → Ideate → Design → Select → Plan → Develop → Complete`
+
+Failure transitions:
+- Any phase may set `status=Errored` but **must** persist the session before exit.
+
+Resume:
+- `Paused → Active` without phase change.
+
+## Export model
+
+**Export root**: `./exports/<sessionId>/`
+
+Minimum contents:
+- `summary.json` (export index + top-level summary)
+- Phase markdown files (names finalized in implementation):
+  - `discover.md`, `ideate.md`, `design.md`, `select.md`, `plan.md`, `develop.md`
+