peaks-cli 1.0.0

package/dist/src/shared/planner-response.js

@@ -0,0 +1,26 @@
+/**
+ * Shared response types for planner commands.
+ * These types ensure consistent error/status reporting across
+ * tech and RD swarm dry-run planner commands.
+ */
+export const WORKSPACE_UNAVAILABLE_NEXT_ACTIONS = Object.freeze([
+    'Configure a Peaks artifact workspace in your workspace config.',
+    'See peaks artifacts workspace --help for setup instructions.',
+]);
+export function makeUnavailableResponse(behavior, reason) {
+    return {
+        available: false,
+        behavior,
+        reason,
+        nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS],
+    };
+}
+export function makeAvailableResponse(data) {
+    return {
+        available: true,
+        data,
+    };
+}
+export function isUnavailableResponse(resp) {
+    return resp.available === false;
+}

package/dist/src/shared/platform.d.ts

@@ -0,0 +1,6 @@
+export type Platform = 'win32' | 'darwin' | 'linux';
+export declare function detectPlatform(currentPlatform?: NodeJS.Platform): Platform;
+export declare const platform: Platform;
+export declare const isWindows: boolean;
+export declare const isMac: boolean;
+export declare const isLinux: boolean;

package/dist/src/shared/platform.js

@@ -0,0 +1,11 @@
+export function detectPlatform(currentPlatform = process.platform) {
+    if (currentPlatform === 'win32')
+        return 'win32';
+    if (currentPlatform === 'darwin')
+        return 'darwin';
+    return 'linux';
+}
+export const platform = detectPlatform();
+export const isWindows = platform === 'win32';
+export const isMac = platform === 'darwin';
+export const isLinux = platform === 'linux';

package/dist/src/shared/process.d.ts

@@ -0,0 +1,5 @@
+export type ExecCommandOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv | undefined;
+};
+export declare function execCommand(command: string, args: string[], options?: ExecCommandOptions): Promise<string>;

package/dist/src/shared/process.js

@@ -0,0 +1,12 @@
+import { execFile } from 'node:child_process';
+export async function execCommand(command, args, options) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { cwd: options?.cwd, env: options?.env }, (error, stdout) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(stdout.trim());
+        });
+    });
+}

package/dist/src/shared/result.d.ts

@@ -0,0 +1,13 @@
+export type ResultEnvelope<T> = {
+    ok: boolean;
+    command: string;
+    data: T;
+    warnings: string[];
+    nextActions: string[];
+    code?: string;
+    message?: string;
+};
+export declare function ok<T>(command: string, data: T, warnings?: string[], nextActions?: string[]): ResultEnvelope<T>;
+export declare function fail<T>(command: string, code: string, message: string, data: T, nextActions?: string[]): ResultEnvelope<T>;
+export declare function getErrorMessage(error: unknown): string;
+export declare function redactSensitiveErrorMessage(message: string): string;

package/dist/src/shared/result.js

@@ -0,0 +1,32 @@
+export function ok(command, data, warnings = [], nextActions = []) {
+    return { ok: true, command, data, warnings, nextActions };
+}
+export function fail(command, code, message, data, nextActions = []) {
+    return { ok: false, command, code, message, data, warnings: [], nextActions };
+}
+const SENSITIVE_ERROR_PATTERNS = [
+    /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/gi,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/g,
+    /\b(?:api[\s_-]?key|token|password|secret)\s*[:=]\s*['\"]?[^\s'\"]{8,}/gi,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bAIza[0-9A-Za-z_-]{20,}\b/g,
+    /\bghp_[0-9A-Za-z_]{20,}\b/g,
+    /\bgithub_pat_[0-9A-Za-z_]{20,}\b/g,
+    /\bglpat-[0-9A-Za-z_-]{20,}\b/g,
+    /\bxox[abprse]-[0-9A-Za-z-]{20,}\b/g,
+    /\bsk-[A-Za-z0-9_-]{16,}\b/g,
+    /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+    /(secret|token|password|api[-_ ]?key)/gi
+];
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'Unexpected error';
+}
+export function redactSensitiveErrorMessage(message) {
+    return SENSITIVE_ERROR_PATTERNS.reduce((redacted, pattern) => redacted.replace(pattern, '[redacted]'), message);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "peaks-cli",
+  "version": "1.0.0",
+  "description": "Peaks CLI and short skill family for Claude Code automation.",
+  "author": "SquabbyZ",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "packageManager": "pnpm@10.11.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "peaks": "./bin/peaks.js"
+  },
+  "files": [
+    "bin/peaks.js",
+    "dist/src/cli/index.js",
+    "dist/src/**/*.js",
+    "dist/src/**/*.d.ts",
+    "scripts/clean-dist.mjs",
+    "scripts/install-skills.mjs",
+    "scripts/watch.mjs",
+    "skills/**",
+    "schemas/*.json"
+  ],
+  "scripts": {
+    "build": "node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "postinstall": "node ./scripts/install-skills.mjs",
+    "dev": "tsx src/cli/index.ts",
+    "dev:watch": "node ./scripts/watch.mjs",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/schemas/approval-record.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Approval Record",
+  "type": "object",
+  "required": ["approvedArtifact", "decision"],
+  "properties": {
+    "approvedBy": { "type": "string" },
+    "approvedAt": { "type": "string" },
+    "approvedArtifact": { "type": "string" },
+    "decision": { "type": "string" },
+    "acceptedRisks": { "type": "array" },
+    "conditions": { "type": "array" }
+  }
+}

package/schemas/artifact-manifest.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Artifact Manifest",
+  "type": "object",
+  "required": ["artifactId", "artifactType", "ownerSkill", "status"],
+  "properties": {
+    "artifactId": { "type": "string" },
+    "artifactType": { "type": "string" },
+    "ownerSkill": { "type": "string" },
+    "scenario": { "type": "string" },
+    "status": { "type": "string" },
+    "inputs": { "type": "array", "items": { "type": "string" } },
+    "outputs": { "type": "array", "items": { "type": "string" } },
+    "evidence": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/artifact-retention-report.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Artifact Retention Report",
+  "type": "object",
+  "required": ["sliceId", "prdArtifacts", "rdArtifacts", "qaArtifacts", "commitStatus"],
+  "properties": {
+    "sliceId": { "type": "string" },
+    "prdArtifacts": { "type": "array", "items": { "type": "string" } },
+    "rdArtifacts": { "type": "array", "items": { "type": "string" } },
+    "qaArtifacts": { "type": "array", "items": { "type": "string" } },
+    "coverageArtifacts": { "type": "array", "items": { "type": "string" } },
+    "reviewArtifacts": { "type": "array", "items": { "type": "string" } },
+    "codeChanges": { "type": "array", "items": { "type": "string" } },
+    "commitStatus": { "type": "string" },
+    "rollbackPoint": { "type": "string" }
+  }
+}

package/schemas/artifact-workspace.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Artifact Workspace",
+  "type": "object",
+  "required": ["workspaceId", "localPath"],
+  "properties": {
+    "workspaceId": { "type": "string" },
+    "artifactRepo": {
+      "type": "object",
+      "required": ["provider", "owner", "name"],
+      "properties": {
+        "provider": { "type": "string", "enum": ["github", "gitlab"] },
+        "owner": { "type": "string" },
+        "name": { "type": "string" },
+        "url": { "type": "string", "format": "uri" }
+      }
+    },
+    "localPath": { "type": "string" },
+    "lastSync": { "type": "string", "format": "date-time" },
+    "syncStatus": { "type": "string", "enum": ["synced", "pending", "out-of-sync", "unknown"] }
+  }
+}

package/schemas/capability-availability.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Capability Availability",
+  "type": "object",
+  "required": ["capabilityId", "type", "status", "requiredFor", "fallback"],
+  "properties": {
+    "capabilityId": { "type": "string" },
+    "type": {
+      "type": "string",
+      "enum": ["skill", "mcp", "cli", "agent", "profile"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["available", "missing", "installable", "disabled", "unknown"]
+    },
+    "requiredFor": { "type": "array", "items": { "type": "string" } },
+    "installPlan": {
+      "type": "object",
+      "properties": {
+        "available": { "type": "boolean" },
+        "commandPreview": { "type": "string" },
+        "requiresApproval": { "type": "boolean" }
+      }
+    },
+    "fallback": {
+      "type": "object",
+      "required": ["mode", "qualityImpact"],
+      "properties": {
+        "mode": { "type": "string" },
+        "qualityImpact": { "type": "string" },
+        "nextAction": { "type": "string" }
+      }
+    },
+    "risk": { "type": "string", "enum": ["low", "medium", "high"] }
+  }
+}

package/schemas/capability-item.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Capability Item",
+  "type": "object",
+  "required": ["capabilityId", "sourceId", "itemType", "category", "workflows", "riskLevel", "fallback"],
+  "properties": {
+    "capabilityId": { "type": "string" },
+    "sourceId": { "type": "string" },
+    "name": { "type": "string" },
+    "itemType": {
+      "type": "string",
+      "enum": ["skill", "agent", "mcp", "rule", "hook", "template", "workflow", "doc", "cli"]
+    },
+    "category": { "type": "string" },
+    "workflows": { "type": "array", "items": { "type": "string" } },
+    "audience": { "type": "array", "items": { "type": "string" } },
+    "riskLevel": { "type": "string", "enum": ["low", "medium", "high"] },
+    "inputContract": { "type": "string" },
+    "outputContract": { "type": "string" },
+    "fallback": {
+      "type": "object",
+      "required": ["mode", "qualityImpact"],
+      "properties": {
+        "mode": { "type": "string" },
+        "qualityImpact": { "type": "string" },
+        "nextAction": { "type": "string" }
+      }
+    },
+    "presentation": {
+      "type": "object",
+      "properties": {
+        "displayName": { "type": "object" },
+        "description": { "type": "object" }
+      }
+    }
+  }
+}

package/schemas/capability-source.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Capability Source",
+  "type": "object",
+  "required": ["sourceId", "sourceType", "title", "url", "discoveryStatus", "items"],
+  "properties": {
+    "sourceId": { "type": "string" },
+    "sourceType": {
+      "type": "string",
+      "enum": ["repo", "skills-package", "mcp-collection", "website", "local-install"]
+    },
+    "title": { "type": "string" },
+    "url": { "type": "string" },
+    "trustSignals": {
+      "type": "object",
+      "properties": {
+        "sourceReputation": { "type": "string" },
+        "stars": { "type": "number" },
+        "installs": { "type": "number" },
+        "maintainer": { "type": "string" },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "discoveryStatus": {
+      "type": "string",
+      "enum": ["unscanned", "indexed", "verified", "deprecated"]
+    },
+    "items": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/change-impact.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Change Impact",
+  "type": "object",
+  "required": ["changeId", "sourceArtifacts", "affectedModules"],
+  "properties": {
+    "changeId": { "type": "string" },
+    "sourceArtifacts": { "type": "array", "items": { "type": "string" } },
+    "affectedModules": { "type": "array", "items": { "type": "string" } },
+    "affectedFiles": { "type": "array", "items": { "type": "string" } },
+    "qaImpact": { "type": "object" },
+    "riskImpact": { "type": "object" },
+    "syncPointers": { "type": "object" }
+  }
+}

package/schemas/context-capsule.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Context Capsule",
+  "type": "object",
+  "required": ["sourceSkill", "audience", "purpose"],
+  "properties": {
+    "sourceSkill": { "type": "string" },
+    "audience": { "type": "array", "items": { "type": "string" } },
+    "purpose": { "type": "string" },
+    "confirmedDecisions": { "type": "array" },
+    "assumptions": { "type": "array" },
+    "discardedOptions": { "type": "array" },
+    "risks": { "type": "array" },
+    "staleness": { "type": "object" }
+  }
+}

package/schemas/recommendation-plan.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Recommendation Plan",
+  "type": "object",
+  "required": ["intent", "workflow", "profile", "audience", "options", "requiredCapabilities", "availability", "decisionRequired", "machine", "presentation"],
+  "properties": {
+    "intent": { "type": "string" },
+    "workflow": { "type": "string" },
+    "profile": { "type": "string" },
+    "audience": { "type": "string" },
+    "options": { "type": "array" },
+    "requiredCapabilities": { "type": "array", "items": { "type": "string" } },
+    "availability": { "type": "array" },
+    "fallbacks": { "type": "array" },
+    "decisionRequired": { "type": "boolean" },
+    "machine": {
+      "type": "object",
+      "required": ["nextActions"],
+      "properties": {
+        "nextActions": { "type": "array" },
+        "constraints": { "type": "array" },
+        "stopConditions": { "type": "array" }
+      }
+    },
+    "presentation": {
+      "type": "object",
+      "required": ["language", "summary", "options"],
+      "properties": {
+        "language": { "type": "string" },
+        "summary": { "type": "string" },
+        "options": { "type": "array" },
+        "warnings": { "type": "array" },
+        "explanations": { "type": "array" }
+      }
+    }
+  }
+}

package/schemas/refactor-slice-spec.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Refactor Slice Spec",
+  "type": "object",
+  "required": ["sliceId", "functionalBoundary", "coverageRequirement", "acceptanceChecks", "commitRequired"],
+  "properties": {
+    "sliceId": { "type": "string" },
+    "functionalBoundary": { "type": "string" },
+    "preRefactorBehavior": { "type": "string" },
+    "targetStructure": { "type": "string" },
+    "nonGoals": { "type": "array" },
+    "unitTestRequirements": { "type": "array" },
+    "coverageRequirement": { "type": "number", "minimum": 95 },
+    "acceptanceChecks": { "type": "array" },
+    "rollbackPlan": { "type": "string" },
+    "requiredArtifacts": { "type": "array" },
+    "commitRequired": { "type": "boolean", "const": true }
+  }
+}

package/scripts/clean-dist.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+rmSync(join(packageRoot, 'dist'), { recursive: true, force: true });

package/scripts/install-skills.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, symlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function getPathStats(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+function linksToSamePath(targetPath, sourcePath) {
+  try {
+    return realpathSync(targetPath) === realpathSync(sourcePath);
+  } catch {
+    return false;
+  }
+}
+
+export function installBundledSkills(options = {}) {
+  const packageRoot = resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
+  const skillsRoot = join(packageRoot, 'skills');
+  const targetRoot = resolve(options.targetRoot ?? process.env.PEAKS_CLAUDE_SKILLS_DIR ?? join(homedir(), '.claude', 'skills'));
+
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
+    return { installed: [], skipped: [] };
+  }
+
+  const installed = [];
+  const skipped = [];
+  mkdirSync(targetRoot, { recursive: true });
+
+  for (const skillName of readdirSync(skillsRoot)) {
+    const sourcePath = join(skillsRoot, skillName);
+    const skillFile = join(sourcePath, 'SKILL.md');
+    const targetPath = join(targetRoot, skillName);
+
+    if (!lstatSync(sourcePath).isDirectory() || !existsSync(skillFile)) {
+      continue;
+    }
+
+    const current = getPathStats(targetPath);
+    if (current) {
+      if (!current.isSymbolicLink() || !linksToSamePath(targetPath, sourcePath)) {
+        skipped.push(skillName);
+        continue;
+      }
+      installed.push(skillName);
+      continue;
+    }
+
+    symlinkSync(sourcePath, targetPath, process.platform === 'win32' ? 'junction' : 'dir');
+    installed.push(skillName);
+  }
+
+  return { installed, skipped };
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const result = installBundledSkills();
+    if (result.installed.length > 0) {
+      process.stdout.write(`Peaks skills linked: ${result.installed.join(', ')}\n`);
+    }
+    if (result.skipped.length > 0) {
+      process.stderr.write(`Peaks skills skipped because local files already exist: ${result.skipped.join(', ')}\n`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Peaks skills were not linked: ${message}\n`);
+    process.exitCode = 1;
+  }
+}