pi-cicd 0.3.0 → 1.0.1

package/docs/QUICKSTART.md

@@ -0,0 +1,99 @@
+# Quick Start - pi-cicd
+
+## Installation
+
+```bash
+pi install npm:pi-cicd
+```
+
+## Basic Usage
+
+### 1. Run Pipeline
+
+```bash
+# Run default pipeline
+/ci run
+
+# Run specific environment
+/ci run production
+
+# Run with variables
+/ci run staging --var=VERSION=1.2.3
+```
+
+### 2. Check Status
+
+```bash
+# Check current run status
+/ci status
+
+# Check specific run
+/ci status --run-id=abc123
+```
+
+### 3. Deploy
+
+```bash
+# Deploy to environment
+/ci deploy production
+
+# Deploy with confirmation
+/ci deploy staging --confirm
+```
+
+### 4. Canary Deployment
+
+```bash
+# Start canary (10% traffic)
+/ci canary deploy --percentage 10
+
+# Increase canary
+/ci canary promote --percentage 25
+
+# Rollback canary
+/ci canary rollback
+```
+
+## Examples
+
+### Example: Production Deploy
+
+```
+/ci run production
+
+Output:
+## CI/CD Pipeline: production
+
+### Stage: build
+✅ npm install (23s)
+✅ npm run build (45s)
+
+### Stage: test
+✅ Unit tests (89 tests, 12s)
+✅ Integration tests (34 tests, 28s)
+
+### Stage: deploy
+🚀 Deploying to production...
+
+✅ Pipeline complete (2m 34s)
+```
+
+### Example: Headless CI
+
+```bash
+# In GitHub Actions
+- name: Run Pi CI
+  run: |
+    pi ci run --headless --exit-code
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Timeout |
+| 10 | Blocked (verification failed) |
+| 11 | Cancelled |
+| 12 | Deployment failed |

package/{dist/index.d.ts → index.ts}

@@ -3,6 +3,20 @@
  *
  * Registers the /ci status command and CI lifecycle hooks.
  */
+
+import type { CIEvent, CIOptions, ExitCode } from "./src/types.ts";
+import { EXIT_CODES } from "./src/types.ts";
+import {
+  ciStatusHandler,
+  createRunTracker,
+  clearRuns,
+  registerRun,
+  type CIRunRecord,
+} from "./src/tools/ci_status.ts";
+import { CIPipeline, type PipelineResult } from "./src/ci/pipeline.ts";
+import { generateReport } from "./src/ci/report.ts";
+
+// Re-export for consumers
 export { EXIT_CODES } from "./src/types.ts";
 export { resolveExitCode } from "./src/headless/exit-codes.ts";
 export { loadAnswers, matchAnswer, parseAnswers } from "./src/headless/answer-injector.ts";
@@ -16,15 +30,23 @@ export { generateReport } from "./src/ci/report.ts";
 export { ciStatusHandler, registerRun, clearRuns, createRunTracker } from "./src/tools/ci_status.ts";
 export { loadCiConfig, DEFAULT_CONFIG } from "./src/config.ts";
 export type { PiCiConfig } from "./src/config.ts";
+
 /**
  * Extension API type (minimal — avoids hard dep on pi-coding-agent types).
  */
 interface ExtensionAPI {
-    registerCommand?: (name: string, handler: (args: unknown) => string | Promise<string>) => void;
-    on?: (event: string, handler: (...args: unknown[]) => void) => void;
+  registerCommand?: (name: string, handler: (args: unknown) => string | Promise<string>) => void;
+  on?: (event: string, handler: (...args: unknown[]) => void) => void;
 }
+
 /**
  * Default export — Pi extension registration.
  */
-export default function piCiExtension(pi: ExtensionAPI): void;
-//# sourceMappingURL=index.d.ts.map
+export default function piCiExtension(pi: ExtensionAPI): void {
+  // Register /ci status command
+  if (pi.registerCommand) {
+    pi.registerCommand("ci", (args: unknown) => {
+      return ciStatusHandler(args);
+    });
+  }
+}

package/install.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Install script for <PKG-NAME>
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const home = os.homedir();
+const agentDir = path.join(home, ".pi", "agent");
+const pkgName = path.basename(process.cwd());
+const configPath = path.join(agentDir, `${pkgName}.json`);
+
+// Create config directory
+fs.mkdirSync(agentDir, { recursive: true });
+
+// Check if config already exists
+if (!fs.existsSync(configPath)) {
+  const defaultConfig = {
+    enabled: true
+  };
+  fs.writeFileSync(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, "utf-8");
+  console.log(`Created default ${pkgName} config: ${configPath}`);
+} else {
+  console.log(`${pkgName} config already exists: ${configPath}`);
+}
+
+console.log(`\nInstall the published package in Pi with:`);
+console.log(`  pi install npm:@baphuongna/${pkgName}`);
+console.log(`\nFor local development from a cloned repo:`);
+console.log(`  pi install .`);
+console.log(`\nVerify installation:`);
+console.log(`  pi list\n`);

package/package.json

@@ -1,25 +1,32 @@
 {
   "name": "pi-cicd",
-  "version": "0.3.0",
-  "description": "Pi extension for headless CI mode with structured exit codes, answer injection, and pipeline automation",
+  "version": "1.0.1",
+  "description": "Extension for Pi coding agent",
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./index.ts",
+  "module": "./index.ts",
+  "types": "./index.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": "./index.ts",
+      "types": "./index.ts"
     }
   },
-  "scripts": {
-    "build": "tsc --noEmitOnError false",
-    "typecheck": "tsc --noEmit",
-    "test": "npx tsx --test --test-concurrency=1 --test-timeout=30000 test/unit/*.test.ts"
-  },
   "files": [
-    "dist"
+    "*.ts",
+    "*.mjs",
+    "src/**/*.ts",
+    "skills/**/*",
+    "README.md",
+    "docs/",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
   "keywords": [
     "pi",
     "coding-agent",
@@ -27,15 +34,8 @@
   ],
   "author": "BaphuongNA",
   "license": "MIT",
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
+  "repository": "https://github.com/baphuongna/pi-cicd",
   "peerDependencies": {
     "typescript": "^5.0.0"
-  },
-  "devDependencies": {
-    "tsx": "^4.19.0"
   }
 }

package/skills/intelligent-deploy/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: intelligent-deploy
+description: Canary deployment with monitoring and landing queue management
+triggers:
+  - deploy
+  - canary
+  - rollout
+  - landing queue
+  - production
+requirements:
+  tools: [bash]
+  context: [deployment target]
+---
+
+# Intelligent Deploy Skill
+
+## Objective
+Execute safe deployments with canary monitoring, automatic rollback, and landing queue management.
+
+## When to Use
+- When user asks to "deploy" or "ship to production"
+- When running CI/CD pipelines
+- When managing multiple deployments
+- When requiring gradual rollouts with monitoring
+
+## Workflow
+
+### Step 1: Canary Deployment
+```typescript
+import { CanaryDeploy } from '../../src/deploy/canary-deploy';
+
+const canary = new CanaryDeploy({
+  initialPercentage: 10,
+  incrementPercentage: 10,
+  stepInterval: 60000, // 1 minute
+  totalDuration: 300000, // 5 minutes
+  metrics: {
+    successRate: { min: 95 },
+    latency: { max: 500 },
+    errorRate: { max: 5 },
+  },
+});
+
+const result = await canary.deploy({
+  name: 'production',
+  url: 'https://api.example.com',
+  healthy: true,
+});
+
+console.log(canary.formatReport(result));
+```
+
+### Step 2: Landing Queue
+```typescript
+import { LandingQueue } from '../../src/deploy/landing-queue';
+
+const queue = new LandingQueue();
+
+// Add to queue
+queue.enqueue('v1.2.0', 'production', 'New feature release');
+queue.enqueue('v1.2.1', 'production', 'Bug fix');
+
+// Process queue
+while (true) {
+  const next = await queue.startNext();
+  if (!next) break;
+  
+  // Deploy
+  const success = await deploy(next);
+  
+  // Mark complete
+  queue.complete(next.id, success);
+  
+  if (!success) break; // Stop on failure
+}
+```
+
+### Step 3: Monitor and Rollback
+```typescript
+// Automatic rollback on issues
+if (result.rolledBack) {
+  console.log('Deployment rolled back due to issues');
+  await canary.rollback(target);
+}
+```
+
+## Canary Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| initialPercentage | 10% | Starting traffic |
+| incrementPercentage | 10% | Traffic increase per step |
+| stepInterval | 1 min | Time between increments |
+| totalDuration | 5 min | Total deployment time |
+
+### Metrics Thresholds
+
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| Success Rate | > 95% | Continue |
+| Latency | < 500ms | Continue |
+| Error Rate | < 5% | Continue |
+
+If metrics drop below thresholds:
+- Warning at threshold
+- Auto-rollback at critical level (90% success, 10% errors)
+
+## Landing Queue Commands
+
+### Enqueue Deployment
+```typescript
+queue.enqueue('v1.2.0', 'production', 'Feature release');
+```
+
+### Process Queue
+```typescript
+while (const next = queue.startNext()) {
+  await deploy(next);
+  queue.complete(next.id, success);
+}
+```
+
+### View Status
+```typescript
+console.log(queue.formatReport());
+```
+
+## Examples
+
+### Deploy with Canary
+```
+User: Deploy v1.2.0 to production with canary
+Agent:
+  const result = await canary.deploy({ name: 'production', url: '...', healthy: true });
+  if (result.success) {
+    console.log('Deployment successful!');
+  } else {
+    console.log('Rolled back - check issues');
+  }
+```
+
+### Process Landing Queue
+```
+User: Queue these deployments: v1.2.0, v1.2.1, v1.2.2
+Agent:
+  queue.enqueue('v1.2.0', 'production');
+  queue.enqueue('v1.2.1', 'production');
+  queue.enqueue('v1.2.2', 'staging');
+  
+  const result = await queue.processAll();
+```
+
+### View Queue Status
+```
+User: Show me the current deployment queue
+Agent:
+  console.log(queue.formatReport());
+```
+
+## Output Format
+
+### Canary Report
+```markdown
+## Canary Deployment Report
+**Status:** ✅ SUCCESS
+**Final Traffic:** 100%
+**Rolled Back:** No
+
+### Metrics History
+| Time | Success | Latency | Error Rate |
+|------|---------|---------|------------|
+| 0min | 98.5% | 120ms | 1.2% |
+| 1min | 99.1% | 115ms | 0.8% |
+| 2min | 99.3% | 110ms | 0.5% |
+```
+
+### Landing Queue Report
+```markdown
+## Landing Queue Report
+**Total:** 5 | **Pending:** 2 | **Deploying:** 1 | **Deployed:** 2 | **Failed:** 0
+
+### Currently Deploying
+**v1.2.1** -> production
+Status: deploying
+
+### Queue
+| # | Version | Environment | Message |
+|---|--------|------------|---------|
+| 1 | v1.2.2 | production | Hotfix |
+| 2 | v1.2.3 | staging | New feature |
+```
+
+## Integration
+
+### With pi-pipeline
+```typescript
+// Run as part of ship workflow
+const gates = new QualityGates();
+const gatesResult = await gates.run('pre-push');
+
+if (gatesResult.passed) {
+  const result = await canary.deploy(target);
+  if (!result.success) {
+    throw new Error('Deployment failed');
+  }
+}
+```
+
+### With pi-audit
+```typescript
+// Security scan before deploy
+const shield = new AgentShield();
+const scan = shield.scan(deploymentCode);
+
+if (!scan.passed) {
+  console.log('Security issues must be fixed');
+  process.exit(1);
+}
+```
+
+### With pi-recollect
+```typescript
+// Remember deployment
+await memory.remember(
+  'deployment',
+  `Deployed ${version} to ${environment}`,
+  'observation'
+);
+```

package/src/ci/pipeline.ts

@@ -0,0 +1,130 @@
+/**
+ * pi-ci — CI pipeline wrapper.
+ *
+ * Provides single, plan, review, and supervised execution modes.
+ */
+
+import type { CIEvent, CIOptions, CIPipelineMode, ExitCode, TestSummary } from "../types.ts";
+import { EXIT_CODES } from "../types.ts";
+import { HeadlessOrchestrator, type OrchestratorHooks } from "../headless/orchestrator.ts";
+import { loadAnswers } from "../headless/answer-injector.ts";
+import { parseTestResults } from "./test-runner.ts";
+import { generateReport } from "./report.ts";
+
+export interface PipelineResult {
+  exitCode: ExitCode;
+  events: CIEvent[];
+  report: string;
+  testSummary?: TestSummary;
+}
+
+export class CIPipeline {
+  private readonly options: CIOptions;
+  private readonly hooks: OrchestratorHooks;
+
+  constructor(options: CIOptions, hooks: OrchestratorHooks) {
+    this.options = options;
+    this.hooks = hooks;
+  }
+
+  /**
+   * Execute the pipeline in the configured mode.
+   */
+  async execute(): Promise<PipelineResult> {
+    switch (this.options.mode) {
+      case "single":
+        return this.executeSingle();
+      case "plan":
+        return this.executePlan();
+      case "review":
+        return this.executeReview();
+      case "supervised":
+        return this.executeSupervised();
+      default:
+        throw new Error(`Unknown CI pipeline mode: ${this.options.mode as string}`);
+    }
+  }
+
+  /**
+   * Single task mode — run one prompt to completion.
+   */
+  private async executeSingle(): Promise<PipelineResult> {
+    const answers = await this.loadAnswers();
+    const orchestrator = new HeadlessOrchestrator(answers, this.options, this.hooks);
+    const result = await orchestrator.run(this.options.prompt, "single");
+
+    return {
+      exitCode: result.exitCode,
+      events: result.events,
+      report: generateReport(result.events),
+    };
+  }
+
+  /**
+   * Plan mode — execute steps from a plan file.
+   *
+   * Each step becomes a sequential orchestrator invocation. If any step fails,
+   * the pipeline stops.
+   */
+  private async executePlan(): Promise<PipelineResult> {
+    const allEvents: CIEvent[] = [];
+    let finalExitCode: ExitCode = EXIT_CODES.SUCCESS;
+    let totalDuration = 0;
+
+    // Plan steps are provided via the executeStep hook — the orchestrator
+    // iterates over steps internally.
+    const answers = await this.loadAnswers();
+    const orchestrator = new HeadlessOrchestrator(answers, this.options, this.hooks);
+    const result = await orchestrator.run(this.options.prompt, "plan");
+
+    allEvents.push(...result.events);
+    finalExitCode = result.exitCode;
+    totalDuration = result.durationMs;
+
+    return {
+      exitCode: finalExitCode,
+      events: allEvents,
+      report: generateReport(allEvents),
+    };
+  }
+
+  /**
+   * PR review mode — review a PR by number.
+   */
+  private async executeReview(): Promise<PipelineResult> {
+    const answers = await this.loadAnswers();
+    const orchestrator = new HeadlessOrchestrator(answers, this.options, this.hooks);
+    const prompt = this.options.prNumber
+      ? `Review PR #${this.options.prNumber}`
+      : this.options.prompt;
+    const result = await orchestrator.run(prompt, "single");
+
+    return {
+      exitCode: result.exitCode,
+      events: result.events,
+      report: generateReport(result.events),
+    };
+  }
+
+  /**
+   * Supervised mode — stdin/stdout forwarding for an external orchestrator.
+   */
+  private async executeSupervised(): Promise<PipelineResult> {
+    const answers = await this.loadAnswers();
+    const orchestrator = new HeadlessOrchestrator(answers, this.options, this.hooks);
+    const result = await orchestrator.run(this.options.prompt, "single");
+
+    return {
+      exitCode: result.exitCode,
+      events: result.events,
+      report: generateReport(result.events),
+    };
+  }
+
+  private async loadAnswers() {
+    if (this.options.answersFile) {
+      return loadAnswers(this.options.answersFile);
+    }
+    return [];
+  }
+}

package/src/ci/pr-creator.ts

@@ -0,0 +1,74 @@
+/**
+ * pi-ci — PR creation via the GitHub CLI (`gh`).
+ *
+ * Wraps `gh pr create` with structured error handling.
+ */
+
+import { execFile } from "node:child_process";
+import type { PROptions, PRResult } from "../types.ts";
+
+/**
+ * Create a pull request using the `gh` CLI.
+ *
+ * Throws if `gh` is not installed or the command fails.
+ */
+export async function createPR(options: PROptions): Promise<PRResult> {
+  const args = ["pr", "create", "--title", options.title];
+
+  if (options.body) {
+    args.push("--body", options.body);
+  }
+  if (options.base) {
+    args.push("--base", options.base);
+  }
+  if (options.head) {
+    args.push("--head", options.head);
+  }
+  if (options.draft) {
+    args.push("--draft");
+  }
+  for (const label of options.labels ?? []) {
+    args.push("--label", label);
+  }
+
+  const output = await runGh(args);
+
+  // Parse the PR URL from the output
+  const urlMatch = output.match(/https:\/\/github\.com\/[^\s]+\/pull\/(\d+)/);
+  if (!urlMatch) {
+    throw new Error(`Failed to parse PR URL from gh output: ${output}`);
+  }
+
+  return {
+    url: urlMatch[0],
+    number: parseInt(urlMatch[1], 10),
+  };
+}
+
+/**
+ * Detect the default (base) branch for the current repository.
+ */
+export async function detectBaseBranch(): Promise<string> {
+  const output = await runGh(["repo", "view", "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"]);
+  return output.trim() || "main";
+}
+
+/**
+ * Execute a `gh` command and return stdout.
+ */
+function runGh(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile("gh", args, { timeout: 60_000 }, (err, stdout, stderr) => {
+      if (err) {
+        const message = stderr?.trim() || err.message;
+        if (err.code === "ENOENT") {
+          reject(new Error("gh CLI is not installed. Install it from https://cli.github.com"));
+        } else {
+          reject(new Error(`gh ${args.join(" ")} failed: ${message}`));
+        }
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}