@realvendex/pi-ci 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# pi-ci
+
+> Pi-native GitHub Actions workflow generator for pi.dev extensions.
+
+## Installation
+
+```bash
+pi install npm:@realvendex/pi-ci
+```
+
+## What It Does
+
+Generate GitHub Actions workflow YAML files pre-configured for pi.dev extension development. Supports three templates (minimal, default, full) with pre-wired jobs for vitest, biome, tsc, npm publish, and GitHub Release.
+
+## Tools
+
+### `ci_generate`
+
+Generate a GitHub Actions CI workflow YAML file.
+
+**Parameters:**
+- `template` (string, optional) — `'minimal'`, `'default'`, or `'full'` (default: `'default'`)
+- `packageName` (string, optional) — Package name for npm publish step
+- `nodeVersion` (string, optional) — Node.js version (default: `'22'`)
+- `includePublish` (boolean, optional) — Include npm publish job (default: false)
+- `includeRelease` (boolean, optional) — Include GitHub Release job (default: false)
+
+**Example:**
+```
+Use the ci_generate tool with template="full" packageName="@realvendex/my-ext"
+```
+
+### `ci_validate`
+
+Validate an existing workflow YAML against pi.dev conventions.
+
+**Parameters:**
+- `yaml` (string, required) — GitHub Actions workflow YAML content to validate
+- `strict` (boolean, optional) — Enable strict pi.dev convention checks (default: false)
+
+**Example:**
+```
+Use the ci_validate tool with yaml="<your workflow YAML>" strict=true
+```
+
+### `ci_init`
+
+Scaffold a `.github/workflows/` directory with a generated CI workflow.
+
+**Parameters:**
+- `template` (string, optional) — `'minimal'`, `'default'`, or `'full'` (default: `'default'`)
+- `packageName` (string, optional) — Package name for npm publish step
+- `dryRun` (boolean, optional) — Preview without writing files (default: false)
+
+**Example:**
+```
+Use the ci_init tool with template="default" dryRun=true
+```
+
+## Templates
+
+| Template  | Jobs                           | Use Case                    |
+|-----------|--------------------------------|-----------------------------|
+| minimal   | CI only                        | Simple projects             |
+| default   | CI + optional publish          | Standard extensions         |
+| full      | CI + publish + GitHub Release  | Full release automation     |
+
+## Pre-wired Jobs
+
+- **ci** — Runs on every push/PR: `biome check`, `tsc --noEmit`, `vitest run`
+- **publish** — Publishes to npm on tag push (requires `NPM_TOKEN` secret)
+- **release** — Creates GitHub Release on tag push
+
+## Resources
+
+- [npm](https://www.npmjs.com/package/@realvendex/pi-ci)
+- [GitHub](https://github.com/ZachDreamZ/pi-ci)
+- [pi.dev](https://pi.dev/packages/@realvendex/pi-ci)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function register(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,17 @@
+import { ciGenerateDef, ciGenerateExecute } from "./tools/ci_generate.js";
+import { ciInitDef, ciInitExecute } from "./tools/ci_init.js";
+import { ciValidateDef, ciValidateExecute } from "./tools/ci_validate.js";
+export default function register(pi) {
+    pi.registerTool({
+        ...ciGenerateDef,
+        execute: ciGenerateExecute,
+    });
+    pi.registerTool({
+        ...ciValidateDef,
+        execute: ciValidateExecute,
+    });
+    pi.registerTool({
+        ...ciInitDef,
+        execute: ciInitExecute,
+    });
+}

package/dist/schemas.d.ts

@@ -0,0 +1,21 @@
+import { type Static, Type } from "typebox";
+export declare const CiGenerateTemplate: Type.TUnion<[Type.TLiteral<"default">, Type.TLiteral<"minimal">, Type.TLiteral<"full">]>;
+export declare const CiGenerateOptions: Type.TObject<{
+    template: Type.TOptional<Type.TUnion<[Type.TLiteral<"default">, Type.TLiteral<"minimal">, Type.TLiteral<"full">]>>;
+    packageName: Type.TOptional<Type.TString>;
+    nodeVersion: Type.TOptional<Type.TString>;
+    includePublish: Type.TOptional<Type.TBoolean>;
+    includeRelease: Type.TOptional<Type.TBoolean>;
+}>;
+export type CiGenerateInput = Static<typeof CiGenerateOptions>;
+export declare const CiValidateOptions: Type.TObject<{
+    yaml: Type.TString;
+    strict: Type.TOptional<Type.TBoolean>;
+}>;
+export type CiValidateInput = Static<typeof CiValidateOptions>;
+export declare const CiInitOptions: Type.TObject<{
+    template: Type.TOptional<Type.TUnion<[Type.TLiteral<"default">, Type.TLiteral<"minimal">, Type.TLiteral<"full">]>>;
+    packageName: Type.TOptional<Type.TString>;
+    dryRun: Type.TOptional<Type.TBoolean>;
+}>;
+export type CiInitInput = Static<typeof CiInitOptions>;

package/dist/schemas.js

@@ -0,0 +1,25 @@
+import { Type } from "typebox";
+// ── ci_generate ──
+export const CiGenerateTemplate = Type.Union([
+    Type.Literal("default"),
+    Type.Literal("minimal"),
+    Type.Literal("full"),
+]);
+export const CiGenerateOptions = Type.Object({
+    template: Type.Optional(CiGenerateTemplate),
+    packageName: Type.Optional(Type.String({ description: "Package name for npm publish step" })),
+    nodeVersion: Type.Optional(Type.String({ description: "Node.js version (default: 22)" })),
+    includePublish: Type.Optional(Type.Boolean({ description: "Include npm publish job (default: false)" })),
+    includeRelease: Type.Optional(Type.Boolean({ description: "Include GitHub Release job (default: false)" })),
+});
+// ── ci_validate ──
+export const CiValidateOptions = Type.Object({
+    yaml: Type.String({ description: "GitHub Actions workflow YAML content to validate" }),
+    strict: Type.Optional(Type.Boolean({ description: "Enable strict pi.dev convention checks (default: false)" })),
+});
+// ── ci_init ──
+export const CiInitOptions = Type.Object({
+    template: Type.Optional(CiGenerateTemplate),
+    packageName: Type.Optional(Type.String({ description: "Package name for npm publish step" })),
+    dryRun: Type.Optional(Type.Boolean({ description: "Preview generated YAML without writing files (default: false)" })),
+});

package/dist/templates.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Workflow YAML template generation for pi.dev extensions.
+ * Generates GitHub Actions workflow files pre-configured for pi.dev standards.
+ */
+export interface WorkflowConfig {
+    packageName?: string;
+    nodeVersion?: string;
+    includePublish?: boolean;
+    includeRelease?: boolean;
+}
+type TemplateName = "default" | "minimal" | "full";
+export declare function generateWorkflow(template: TemplateName, config: WorkflowConfig): string;
+export declare function listTemplates(): Array<{
+    name: string;
+    description: string;
+}>;
+export type { TemplateName };

package/dist/templates.js

@@ -0,0 +1,126 @@
+/**
+ * Workflow YAML template generation for pi.dev extensions.
+ * Generates GitHub Actions workflow files pre-configured for pi.dev standards.
+ */
+// ── Template definitions ──
+function ciJob(config) {
+    const node = config.nodeVersion ?? "22";
+    return `    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [${node}]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: \${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npx biome check .
+      - run: npx tsc --noEmit
+      - run: npx vitest run`;
+}
+function publishJob(config) {
+    const _pkg = config.packageName ?? "@realvendex/pi-extension";
+    return `    needs: ci
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }}`;
+}
+function releaseJob() {
+    return `    needs: ci
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true`;
+}
+// ── Template generators ──
+function minimalTemplate(config) {
+    return `name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+${ciJob(config)}`;
+}
+function defaultTemplate(config) {
+    let yaml = `name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+${ciJob(config)}`;
+    if (config.includePublish) {
+        yaml += `
+
+  publish:
+${publishJob(config)}`;
+    }
+    return yaml;
+}
+function fullTemplate(config) {
+    let yaml = `name: CI/CD
+on:
+  push:
+    branches: [main]
+    tags: [v*]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+${ciJob(config)}
+
+  publish:
+${publishJob(config)}`;
+    if (config.includeRelease !== false) {
+        yaml += `
+
+  release:
+${releaseJob()}`;
+    }
+    return yaml;
+}
+// ── Public API ──
+const TEMPLATES = {
+    minimal: minimalTemplate,
+    default: defaultTemplate,
+    full: fullTemplate,
+};
+export function generateWorkflow(template, config) {
+    const generator = TEMPLATES[template];
+    if (!generator) {
+        throw new Error(`Unknown template: ${template}. Available: ${Object.keys(TEMPLATES).join(", ")}`);
+    }
+    return generator(config);
+}
+export function listTemplates() {
+    return [
+        { name: "minimal", description: "Single CI job: lint, typecheck, test" },
+        { name: "default", description: "CI job + optional publish on tag push" },
+        { name: "full", description: "CI + publish + GitHub Release on tag push" },
+    ];
+}

package/dist/tools/ci_generate.d.ts

@@ -0,0 +1,21 @@
+import { Type } from "typebox";
+import { type CiGenerateInput } from "../schemas.js";
+export declare const ciGenerateDef: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        template: Type.TOptional<Type.TUnion<[Type.TLiteral<"default">, Type.TLiteral<"minimal">, Type.TLiteral<"full">]>>;
+        packageName: Type.TOptional<Type.TString>;
+        nodeVersion: Type.TOptional<Type.TString>;
+        includePublish: Type.TOptional<Type.TBoolean>;
+        includeRelease: Type.TOptional<Type.TBoolean>;
+    }>;
+};
+export declare function ciGenerateExecute(_toolCallId: string, params: CiGenerateInput): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: Record<string, unknown>;
+}>;

package/dist/tools/ci_generate.js

@@ -0,0 +1,48 @@
+import { CiGenerateOptions } from "../schemas.js";
+import { generateWorkflow, listTemplates } from "../templates.js";
+export const ciGenerateDef = {
+    name: "ci_generate",
+    label: "Generate CI Workflow",
+    description: "Generate a GitHub Actions workflow YAML file for a pi.dev extension. Produces CI/CD workflow with test (vitest), lint (biome), typecheck (tsc), and optional publish/release jobs.",
+    parameters: CiGenerateOptions,
+};
+export async function ciGenerateExecute(_toolCallId, params) {
+    const template = params.template ?? "default";
+    const config = {
+        packageName: params.packageName,
+        nodeVersion: params.nodeVersion,
+        includePublish: params.includePublish,
+        includeRelease: params.includeRelease,
+    };
+    const yaml = generateWorkflow(template, config);
+    const templates = listTemplates();
+    const templateInfo = templates.find((t) => t.name === template);
+    return {
+        content: [{ type: "text", text: yaml }],
+        details: {
+            template,
+            templateDescription: templateInfo?.description ?? "",
+            jobs: extractJobNames(yaml),
+            nodeVersion: config.nodeVersion ?? "22",
+            includePublish: config.includePublish ?? false,
+            includeRelease: config.includeRelease ?? template === "full",
+        },
+    };
+}
+function extractJobNames(yaml) {
+    const jobs = [];
+    const lines = yaml.split("\n");
+    let inJobs = false;
+    for (const line of lines) {
+        if (line.trim() === "jobs:") {
+            inJobs = true;
+            continue;
+        }
+        if (inJobs && line.match(/^ {2}\w/)) {
+            const match = line.match(/^ {2}(\w[\w-]*):/);
+            if (match)
+                jobs.push(match[1]);
+        }
+    }
+    return jobs;
+}

package/dist/tools/ci_init.d.ts

@@ -0,0 +1,19 @@
+import { Type } from "typebox";
+import { type CiInitInput } from "../schemas.js";
+export declare const ciInitDef: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        template: Type.TOptional<Type.TUnion<[Type.TLiteral<"default">, Type.TLiteral<"minimal">, Type.TLiteral<"full">]>>;
+        packageName: Type.TOptional<Type.TString>;
+        dryRun: Type.TOptional<Type.TBoolean>;
+    }>;
+};
+export declare function ciInitExecute(_toolCallId: string, params: CiInitInput): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: Record<string, unknown>;
+}>;

package/dist/tools/ci_init.js

@@ -0,0 +1,55 @@
+import { CiInitOptions } from "../schemas.js";
+import { generateWorkflow } from "../templates.js";
+export const ciInitDef = {
+    name: "ci_init",
+    label: "Initialize CI Workflow",
+    description: "Scaffold a .github/workflows/ directory with a generated CI workflow YAML. Supports dry-run mode to preview without writing files.",
+    parameters: CiInitOptions,
+};
+export async function ciInitExecute(_toolCallId, params) {
+    const template = params.template ?? "default";
+    const config = {
+        packageName: params.packageName,
+        includePublish: template === "full" || template === "default",
+        includeRelease: template === "full",
+    };
+    const yaml = generateWorkflow(template, config);
+    const dryRun = params.dryRun ?? false;
+    const workflowPath = ".github/workflows/ci.yml";
+    if (dryRun) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Dry Run — Preview\n\nWould write to: ${workflowPath}\n\n---\n\n${yaml}`,
+                },
+            ],
+            details: {
+                dryRun: true,
+                path: workflowPath,
+                template,
+                yaml,
+                written: false,
+            },
+        };
+    }
+    // In real mode we return the path + content for the caller to write.
+    // Tools in pi.dev don't have filesystem access by default — we provide
+    // the content and let the extension host write it.
+    return {
+        content: [
+            {
+                type: "text",
+                text: `# CI Workflow Ready\n\nWrite the following to \`${workflowPath}\`:\n\n\`\`\`yaml\n${yaml}\n\`\`\``,
+            },
+        ],
+        details: {
+            dryRun: false,
+            path: workflowPath,
+            template,
+            yaml,
+            written: false,
+            instruction: `Create directory .github/workflows/ and write the YAML content to ${workflowPath}`,
+        },
+    };
+}

package/dist/tools/ci_validate.d.ts

@@ -0,0 +1,18 @@
+import { Type } from "typebox";
+import { type CiValidateInput } from "../schemas.js";
+export declare const ciValidateDef: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        yaml: Type.TString;
+        strict: Type.TOptional<Type.TBoolean>;
+    }>;
+};
+export declare function ciValidateExecute(_toolCallId: string, params: CiValidateInput): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: Record<string, unknown>;
+}>;

package/dist/tools/ci_validate.js

@@ -0,0 +1,153 @@
+import { CiValidateOptions } from "../schemas.js";
+export const ciValidateDef = {
+    name: "ci_validate",
+    label: "Validate CI Workflow",
+    description: "Validate an existing GitHub Actions workflow YAML. Checks structure, required jobs, triggers, and pi.dev-specific conventions (Node version, npm scope, etc.).",
+    parameters: CiValidateOptions,
+};
+export async function ciValidateExecute(_toolCallId, params) {
+    const issues = validateWorkflow(params.yaml, params.strict ?? false);
+    const errors = issues.filter((i) => i.level === "error");
+    const warnings = issues.filter((i) => i.level === "warning");
+    const infos = issues.filter((i) => i.level === "info");
+    const report = buildReport(issues, errors.length === 0);
+    return {
+        content: [{ type: "text", text: report }],
+        details: {
+            valid: errors.length === 0,
+            errors: errors.length,
+            warnings: warnings.length,
+            infos: infos.length,
+            issues,
+        },
+    };
+}
+function validateWorkflow(yaml, strict) {
+    const issues = [];
+    const lines = yaml.split("\n");
+    // ── Structure checks ──
+    const hasOnTrigger = lines.some((l) => /^\s*on\s*:/.test(l) && !/runs-on/.test(l));
+    if (!hasOnTrigger) {
+        issues.push({ level: "error", message: "Missing 'on:' trigger section" });
+    }
+    if (!yaml.includes("jobs:")) {
+        issues.push({ level: "error", message: "Missing 'jobs:' section" });
+    }
+    // ── Job checks ──
+    const hasCi = yaml.includes("ci:");
+    const hasTest = yaml.includes("vitest") || yaml.includes("jest") || yaml.includes("test:");
+    const hasLint = yaml.includes("biome") || yaml.includes("eslint") || yaml.includes("lint:");
+    const hasTypecheck = yaml.includes("tsc") || yaml.includes("typecheck");
+    if (!hasCi) {
+        issues.push({ level: "warning", message: "No 'ci' job found — consider adding a main CI job" });
+    }
+    if (hasCi && !hasTest) {
+        issues.push({ level: "warning", message: "CI job does not run tests (expected vitest)" });
+    }
+    if (hasCi && !hasLint) {
+        issues.push({ level: "warning", message: "CI job does not run linting (expected biome)" });
+    }
+    if (hasCi && !hasTypecheck) {
+        issues.push({
+            level: "warning",
+            message: "CI job does not run type checking (expected tsc --noEmit)",
+        });
+    }
+    // ── Node version ──
+    const nodeVersionMatch = yaml.match(/node-version:\s*\[?(\d+)/);
+    if (nodeVersionMatch) {
+        const version = Number.parseInt(nodeVersionMatch[1], 10);
+        if (version < 20) {
+            issues.push({
+                level: "error",
+                message: `Node.js version ${version} is below minimum (20). pi.dev requires Node 20+`,
+            });
+        }
+        else if (version < 22 && strict) {
+            issues.push({
+                level: "warning",
+                message: `Node.js version ${version} — pi.dev recommends Node 22 LTS`,
+            });
+        }
+    }
+    else {
+        issues.push({
+            level: "warning",
+            message: "No Node.js version specified — pi.dev recommends Node 22 LTS",
+        });
+    }
+    // ── Trigger checks ──
+    if (!yaml.includes("push:")) {
+        issues.push({ level: "info", message: "No push trigger — CI only runs on PRs" });
+    }
+    if (!yaml.includes("pull_request:")) {
+        issues.push({ level: "info", message: "No pull_request trigger — CI only runs on push" });
+    }
+    // ── Strict checks ──
+    if (strict) {
+        if (!yaml.includes("registry-url")) {
+            issues.push({
+                level: "warning",
+                message: "Missing registry-url in setup-node (needed for npm publish)",
+            });
+        }
+        if (!yaml.includes("npm ci")) {
+            issues.push({
+                level: "warning",
+                message: "Using 'npm install' instead of 'npm ci' — ci is preferred in CI",
+            });
+        }
+        if (yaml.includes("npm install") && !yaml.includes("npm ci")) {
+            issues.push({
+                level: "error",
+                message: "Use 'npm ci' instead of 'npm install' for reproducible builds",
+            });
+        }
+        if (yaml.includes("actions/checkout@v3") || yaml.includes("actions/setup-node@v3")) {
+            issues.push({
+                level: "warning",
+                message: "Using v3 actions — v4 is current (faster, smaller)",
+            });
+        }
+    }
+    // ── Security ──
+    if (yaml.includes("secrets.NPM_TOKEN") && !yaml.includes("refs/tags")) {
+        issues.push({
+            level: "warning",
+            message: "NPM_TOKEN available on all pushes — restrict to tag pushes for safety",
+        });
+    }
+    if (issues.length === 0) {
+        issues.push({ level: "info", message: "No issues found — workflow looks good!" });
+    }
+    return issues;
+}
+function buildReport(issues, valid) {
+    const lines = [];
+    lines.push("# Workflow Validation Report");
+    lines.push("");
+    lines.push(`Status: ${valid ? "✅ VALID" : "❌ INVALID"}`);
+    lines.push("");
+    const errors = issues.filter((i) => i.level === "error");
+    const warnings = issues.filter((i) => i.level === "warning");
+    const infos = issues.filter((i) => i.level === "info");
+    if (errors.length > 0) {
+        lines.push(`## Errors (${errors.length})`);
+        for (const e of errors)
+            lines.push(`  ❌ ${e.message}`);
+        lines.push("");
+    }
+    if (warnings.length > 0) {
+        lines.push(`## Warnings (${warnings.length})`);
+        for (const w of warnings)
+            lines.push(`  ⚠️  ${w.message}`);
+        lines.push("");
+    }
+    if (infos.length > 0) {
+        lines.push(`## Info (${infos.length})`);
+        for (const i of infos)
+            lines.push(`  ℹ️  ${i.message}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@realvendex/pi-ci",
+  "version": "1.0.0",
+  "description": "Pi-native GitHub Actions workflow generator for pi.dev extensions — pre-configured test, lint, build, and publish jobs.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "format": "biome check --write ."
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "ci-cd",
+    "github-actions",
+    "workflow",
+    "automation",
+    "devops"
+  ],
+  "author": "realvendex",
+  "license": "MIT",
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "typescript": "^5.5.0",
+    "typebox": "^1.0.0",
+    "vitest": "^2.0.0"
+  },
+  "pi": {
+    "extensions": ["./dist"]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZachDreamZ/pi-ci.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ZachDreamZ/pi-ci/issues"
+  },
+  "homepage": "https://github.com/ZachDreamZ/pi-ci#readme"
+}