peaks-cli 1.0.0

package/dist/src/services/workflow/workflow-router-service.d.ts

@@ -0,0 +1,85 @@
+import { type ModelProviderConfig, type WorkspaceConfig } from '../config/config-types.js';
+import { type RdPlanResult } from '../rd/rd-service.js';
+import { type TechPlanResult, type TechStatus } from '../tech/tech-service.js';
+export type WorkflowMode = 'solo' | 'team';
+export type SoloMode = 'full-auto' | 'guided' | 'rnd';
+export type ModelTier = 'top-tier' | 'mid-tier';
+export type ModelRole = 'strongest' | 'execution';
+export type WorkflowRoutePolicy = 'solo-broad-multi-model' | 'team-rd-limited-multi-model';
+export type WorkflowStepStage = 'product-direction' | 'design-direction' | 'tech-direction' | 'tech-review' | 'rd-planning' | 'coding-execution' | 'unit-test-execution' | 'quality-review';
+export type WorkflowStepOwner = 'peaks-solo' | 'peaks-rd' | 'peaks-tech' | 'human';
+export type WorkflowRouterRequest = {
+    changeId: string;
+    goal: string;
+    mode: WorkflowMode;
+    soloMode?: SoloMode;
+    maxWorkers?: number;
+    dryRun: true;
+    artifactWorkspacePath?: string;
+    workspace?: WorkspaceConfig;
+    config?: {
+        economyMode?: boolean;
+        swarmMode?: boolean;
+        providers?: ModelProviderConfig;
+    };
+};
+export type WorkflowRouterStep = {
+    readonly id: string;
+    readonly stage: WorkflowStepStage;
+    readonly owner: WorkflowStepOwner;
+    readonly modelTier: ModelTier;
+    readonly modelRole: ModelRole;
+    readonly modelId: string;
+    readonly reason: string;
+    readonly dryRunOnly: true;
+    readonly invokesAgents: false;
+    readonly writesArtifacts: false;
+    readonly dependsOn: readonly string[];
+};
+export type WorkflowModelRouting = {
+    readonly strongestModel: {
+        readonly modelId: 'claude-opus-4-7';
+        readonly uses: readonly WorkflowStepStage[];
+    };
+    readonly executionModel: {
+        readonly modelId: string;
+        readonly uses: readonly WorkflowStepStage[];
+    };
+};
+export type WorkflowModelAssignment = {
+    readonly stage: WorkflowStepStage;
+    readonly owner: WorkflowStepOwner;
+    readonly modelTier: ModelTier;
+    readonly modelRole: ModelRole;
+    readonly modelId: string;
+};
+export type WorkflowModeStatus = {
+    readonly economyModeEnabled: boolean;
+    readonly swarmModeEnabled: boolean;
+    readonly executionModelId: string;
+    readonly executionModelSource: string;
+    readonly summary: string;
+};
+export type WorkflowRouterPlan = {
+    readonly changeId: string;
+    readonly goal: string;
+    readonly mode: WorkflowMode;
+    readonly soloMode?: SoloMode;
+    readonly executionMode: 'autonomous';
+    readonly decisionProfile: string;
+    readonly dryRun: true;
+    readonly routePolicy: WorkflowRoutePolicy;
+    readonly modelRouting: WorkflowModelRouting;
+    readonly modelAssignments: readonly WorkflowModelAssignment[];
+    readonly modeStatus: WorkflowModeStatus;
+    readonly techStatus: TechStatus;
+    readonly techPlan: TechPlanResult;
+    readonly rdPlan: RdPlanResult;
+    readonly steps: readonly WorkflowRouterStep[];
+    readonly blockedReasons: readonly string[];
+    readonly nextActions: readonly string[];
+    readonly constraints: readonly string[];
+};
+export declare function isWorkflowMode(mode: string): mode is WorkflowMode;
+export declare function isSoloMode(value: string): value is SoloMode;
+export declare function createWorkflowRouterPlan(request: WorkflowRouterRequest): WorkflowRouterPlan;

package/dist/src/services/workflow/workflow-router-service.js

@@ -0,0 +1,213 @@
+import { DEFAULT_CONFIG } from '../config/config-types.js';
+import { getConfiguredExecutionModelId, STRONGEST_MODEL_ID } from '../config/model-routing.js';
+import { getLocalArtifactPath } from '../artifacts/workspace-service.js';
+import { createRdSwarmPlan } from '../rd/rd-service.js';
+import { createTechPlan, getTechStatus } from '../tech/tech-service.js';
+import { validateChangeIdOrThrow } from '../../shared/change-id.js';
+import { WORKSPACE_UNAVAILABLE_NEXT_ACTIONS } from '../../shared/planner-response.js';
+const WORKFLOW_CONSTRAINTS = Object.freeze([
+    'dry-run-only',
+    'requires-swarm-execution-for-rd-and-qa-when-enabled',
+    'execution-model-from-config-providers',
+    'do-not-launch-agents',
+    'do-not-write-artifacts',
+    'do-not-mutate-target-repo'
+]);
+const EXECUTION_STAGES = ['coding-execution', 'unit-test-execution'];
+const GUIDED_DECISION_STAGES = ['product-direction', 'design-direction'];
+const GOVERNED_DECISION_STAGES = ['product-direction', 'design-direction', 'tech-direction', 'tech-review'];
+export function isWorkflowMode(mode) {
+    return mode === 'solo' || mode === 'team';
+}
+function assertSupportedMode(mode) {
+    if (!isWorkflowMode(mode)) {
+        throw new Error('Unsupported workflow mode');
+    }
+}
+function normalizeGoal(goal) {
+    const normalized = goal.trim();
+    if (!normalized) {
+        throw new Error('Goal must be non-empty');
+    }
+    return normalized;
+}
+function assertSoloModeAllowed(mode, soloMode) {
+    if (mode !== 'solo' && soloMode !== undefined) {
+        throw new Error('soloMode requires solo workflow mode');
+    }
+}
+function step(input, executionModelId) {
+    const modelRole = EXECUTION_STAGES.includes(input.stage) ? 'execution' : 'strongest';
+    return {
+        ...input,
+        modelRole,
+        modelId: modelRole === 'execution' ? executionModelId : STRONGEST_MODEL_ID,
+        dryRunOnly: true,
+        invokesAgents: false,
+        writesArtifacts: false
+    };
+}
+export function isSoloMode(value) {
+    return value === 'full-auto' || value === 'guided' || value === 'rnd';
+}
+function getDecisionProfileSummary(mode, soloMode) {
+    if (mode === 'team') {
+        return 'Team mode keeps product and design governance on a human-controlled path while RD execution follows recommended defaults.';
+    }
+    if (soloMode === 'guided') {
+        return 'Guided mode keeps the user in the decision loop for the early recommended defaults, while later execution remains bounded by the routing plan.';
+    }
+    if (soloMode === 'rnd') {
+        return 'R&D mode asks for technical confirmation up front, then applies recommended defaults for implementation, testing, review, and safety checks.';
+    }
+    return 'Full-auto mode applies recommended defaults for product, design, and tech decisions, then runs the engineering pipeline end to end under routing gates.';
+}
+function annotateSteps(steps, soloMode) {
+    const decisionStages = soloMode === 'guided'
+        ? GUIDED_DECISION_STAGES
+        : GOVERNED_DECISION_STAGES;
+    return steps.map((currentStep) => {
+        const isDecisionStage = decisionStages.includes(currentStep.stage);
+        const reasonPrefix = isDecisionStage
+            ? `[${soloMode}] decision stage`
+            : '[routed] execution stage';
+        return {
+            ...currentStep,
+            reason: `${reasonPrefix}: ${currentStep.reason}`
+        };
+    });
+}
+function createSoloSteps(executionModelId) {
+    return [
+        step({ id: 'solo-product-direction', stage: 'product-direction', owner: 'peaks-solo', modelTier: 'top-tier', reason: 'Product direction needs strong judgment before execution work is delegated.', dependsOn: [] }, executionModelId),
+        step({ id: 'solo-design-direction', stage: 'design-direction', owner: 'peaks-solo', modelTier: 'top-tier', reason: 'Design direction uses the recommended default before cheaper implementation work.', dependsOn: ['solo-product-direction'] }, executionModelId),
+        step({ id: 'solo-tech-direction', stage: 'tech-direction', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Technical boundaries and approval gates use the recommended default with high-confidence planning.', dependsOn: ['solo-design-direction'] }, executionModelId),
+        step({ id: 'solo-tech-review', stage: 'tech-review', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Tech artifacts and gate decisions require strong review and a recommended default path.', dependsOn: ['solo-tech-direction'] }, executionModelId),
+        step({ id: 'solo-rd-planning', stage: 'rd-planning', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'RD task decomposition and acceptance criteria use the recommended default before execution delegation.', dependsOn: ['solo-tech-review'] }, executionModelId),
+        step({ id: 'solo-coding-execution', stage: 'coding-execution', owner: 'peaks-rd', modelTier: executionModelId === STRONGEST_MODEL_ID ? 'top-tier' : 'mid-tier', reason: `Coding and routine refactoring must use the configured execution worker model ${executionModelId}.`, dependsOn: ['solo-rd-planning'] }, executionModelId),
+        step({ id: 'solo-unit-test-execution', stage: 'unit-test-execution', owner: 'peaks-rd', modelTier: executionModelId === STRONGEST_MODEL_ID ? 'top-tier' : 'mid-tier', reason: `Unit test authoring and focused test runs must use the configured execution worker model ${executionModelId}.`, dependsOn: ['solo-coding-execution'] }, executionModelId),
+        step({ id: 'solo-quality-review', stage: 'quality-review', owner: 'peaks-solo', modelTier: 'top-tier', reason: 'Reducer and final quality gates need strong synthesis and risk review.', dependsOn: ['solo-unit-test-execution'] }, executionModelId)
+    ];
+}
+function createSoloStepsForMode(soloMode, executionModelId) {
+    return annotateSteps(createSoloSteps(executionModelId), soloMode);
+}
+function createTeamSteps(executionModelId) {
+    return [
+        step({ id: 'team-product-direction', stage: 'product-direction', owner: 'human', modelTier: 'top-tier', reason: 'Team product direction should stay on the governed planning path.', dependsOn: [] }, executionModelId),
+        step({ id: 'team-design-direction', stage: 'design-direction', owner: 'human', modelTier: 'top-tier', reason: 'Team design direction should preserve reviewability and accountability.', dependsOn: ['team-product-direction'] }, executionModelId),
+        step({ id: 'team-tech-direction', stage: 'tech-direction', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Team technical plans should remain strongly governed before RD execution.', dependsOn: ['team-design-direction'] }, executionModelId),
+        step({ id: 'team-tech-review', stage: 'tech-review', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Team tech approval requires strong review before execution.', dependsOn: ['team-tech-direction'] }, executionModelId),
+        step({ id: 'team-rd-planning', stage: 'rd-planning', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'Team RD task decomposition remains on the governed strongest-model path.', dependsOn: ['team-tech-review'] }, executionModelId),
+        step({ id: 'team-coding-execution', stage: 'coding-execution', owner: 'peaks-rd', modelTier: executionModelId === STRONGEST_MODEL_ID ? 'top-tier' : 'mid-tier', reason: `Bounded coding tasks must use the configured execution worker model ${executionModelId}.`, dependsOn: ['team-rd-planning'] }, executionModelId),
+        step({ id: 'team-unit-test-execution', stage: 'unit-test-execution', owner: 'peaks-rd', modelTier: executionModelId === STRONGEST_MODEL_ID ? 'top-tier' : 'mid-tier', reason: `Unit-test tasks must use the configured execution worker model ${executionModelId}.`, dependsOn: ['team-coding-execution'] }, executionModelId),
+        step({ id: 'team-quality-review', stage: 'quality-review', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'Team RD outputs still need reducer and quality review gates.', dependsOn: ['team-unit-test-execution'] }, executionModelId)
+    ];
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function createModelRouting(steps, executionModelId) {
+    return {
+        strongestModel: {
+            modelId: STRONGEST_MODEL_ID,
+            uses: steps.filter((step) => step.modelRole === 'strongest').map((step) => step.stage)
+        },
+        executionModel: {
+            modelId: executionModelId,
+            uses: steps.filter((step) => step.modelRole === 'execution').map((step) => step.stage)
+        }
+    };
+}
+function createModelAssignments(steps) {
+    return steps.map((step) => ({
+        stage: step.stage,
+        owner: step.owner,
+        modelTier: step.modelTier,
+        modelRole: step.modelRole,
+        modelId: step.modelId
+    }));
+}
+function getTechPlanBlockedReasons(techPlan) {
+    return techPlan.available ? techPlan.blockedReasons : techPlan.preview.blockedReasons;
+}
+function getTechPlanNextActions(techPlan) {
+    return [...techPlan.nextActions];
+}
+function createModeStatus(economyMode, swarmMode, executionModelId, executionModelSource) {
+    const economySummary = economyMode
+        ? `Economy mode enabled: code worker and test worker strictly use ${executionModelId} from config providers.`
+        : `Economy mode disabled: code worker and test worker use ${STRONGEST_MODEL_ID}, matching planner/reviewer.`;
+    const swarmSummary = swarmMode
+        ? 'Swarm mode enabled: peaks-rd coding, unit-test, and peaks-qa quality work must be represented as swarm worker tasks.'
+        : 'Swarm mode disabled: swarm worker graph generation is bypassed.';
+    return {
+        economyModeEnabled: economyMode,
+        swarmModeEnabled: swarmMode,
+        executionModelId,
+        executionModelSource,
+        summary: `${economySummary} ${swarmSummary}`
+    };
+}
+function getSoloMode(mode, soloMode) {
+    if (mode !== 'solo') {
+        return undefined;
+    }
+    if (soloMode === undefined) {
+        return 'full-auto';
+    }
+    if (!isSoloMode(soloMode)) {
+        throw new Error('Unsupported solo mode');
+    }
+    return soloMode;
+}
+export function createWorkflowRouterPlan(request) {
+    assertSupportedMode(request.mode);
+    assertSoloModeAllowed(request.mode, request.soloMode);
+    validateChangeIdOrThrow(request.changeId);
+    const goal = normalizeGoal(request.goal);
+    const maxWorkers = request.maxWorkers ?? 40;
+    const economyMode = request.config?.economyMode ?? DEFAULT_CONFIG.economyMode;
+    const swarmMode = request.config?.swarmMode ?? DEFAULT_CONFIG.swarmMode;
+    const executionModelId = economyMode ? getConfiguredExecutionModelId(request.config?.providers) : STRONGEST_MODEL_ID;
+    const modeStatus = createModeStatus(economyMode, swarmMode, executionModelId, economyMode ? 'config.providers' : 'planner-reviewer-strongest-model');
+    const soloMode = getSoloMode(request.mode, request.soloMode);
+    const decisionProfile = getDecisionProfileSummary(request.mode, soloMode);
+    const artifactWorkspacePath = request.artifactWorkspacePath ?? (request.workspace ? getLocalArtifactPath(request.workspace) : undefined);
+    const sharedWorkspaceOptions = {
+        ...(artifactWorkspacePath ? { artifactWorkspacePath } : {}),
+        ...(request.workspace ? { workspace: request.workspace } : {})
+    };
+    const techStatus = getTechStatus({ changeId: request.changeId, ...sharedWorkspaceOptions });
+    const techPlan = createTechPlan({ changeId: request.changeId, goal, swarm: swarmMode, dryRun: true, ...sharedWorkspaceOptions });
+    const rdPlan = createRdSwarmPlan({ skill: 'rd', changeId: request.changeId, goal, maxWorkers, swarmMode, executionModelId, dryRun: true, ...sharedWorkspaceOptions });
+    const steps = soloMode ? createSoloStepsForMode(soloMode, executionModelId) : createTeamSteps(executionModelId);
+    const blockedReasons = uniqueStrings([
+        ...techStatus.blockedReasons,
+        ...getTechPlanBlockedReasons(techPlan),
+        ...rdPlan.blockedReasons
+    ]);
+    const nextActions = blockedReasons.includes('artifact-workspace-unavailable')
+        ? [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS]
+        : uniqueStrings([...techStatus.nextActions, ...getTechPlanNextActions(techPlan), ...rdPlan.nextActions]);
+    return {
+        changeId: request.changeId,
+        goal,
+        mode: request.mode,
+        ...(soloMode ? { soloMode } : {}),
+        executionMode: 'autonomous',
+        decisionProfile,
+        dryRun: true,
+        routePolicy: request.mode === 'solo' ? 'solo-broad-multi-model' : 'team-rd-limited-multi-model',
+        modelRouting: createModelRouting(steps, executionModelId),
+        modelAssignments: createModelAssignments(steps),
+        modeStatus,
+        techStatus,
+        techPlan,
+        rdPlan,
+        steps,
+        blockedReasons,
+        nextActions,
+        constraints: [...WORKFLOW_CONSTRAINTS]
+    };
+}

package/dist/src/shared/change-id.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared change-id validation and artifact path helpers.
+ * All Peaks planner commands must use these to prevent path traversal
+ * and keep artifacts inside the Peaks artifact workspace.
+ */
+export declare function isValidChangeId(changeId: string): boolean;
+export declare function isUnsafePathInput(input: string): boolean;
+export declare function validateChangeIdOrThrow(changeId: string): void;
+export declare class ChangeIdValidationError extends Error {
+    readonly changeId: string;
+    constructor(changeId: string);
+}
+export declare function isUnsafeArtifactPath(path: string): boolean;
+export declare function buildArtifactRelativePath(changeId: string, ...segments: string[]): string;
+export declare function isPathInsideArtifactRoot(path: string, artifactRoot: string): boolean;

package/dist/src/shared/change-id.js

@@ -0,0 +1,76 @@
+/**
+ * Shared change-id validation and artifact path helpers.
+ * All Peaks planner commands must use these to prevent path traversal
+ * and keep artifacts inside the Peaks artifact workspace.
+ */
+import { posix } from 'node:path';
+const CHANGE_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+function normalizeForwardSlashes(input) {
+    return input.replace(/\\/g, '/');
+}
+function hasUnsafePathShape(input) {
+    const normalized = normalizeForwardSlashes(input);
+    if (input.includes('\\'))
+        return true;
+    if (!normalized || normalized === '.' || normalized === '..')
+        return true;
+    if (normalized.startsWith('/') || normalized.startsWith('//'))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    if (normalized.includes('://'))
+        return true;
+    if (/^[^@\s]+@[^:\s]+:.+/.test(normalized))
+        return true;
+    return normalized.split('/').some((segment) => segment.length === 0 || segment === '.' || segment === '..');
+}
+function normalizeArtifactPath(input) {
+    const normalized = posix.normalize(normalizeForwardSlashes(input));
+    return normalized.replace(/\/$/, '');
+}
+export function isValidChangeId(changeId) {
+    if (!changeId || changeId.length === 0)
+        return false;
+    if (changeId === '.' || changeId === '..')
+        return false;
+    if (changeId.includes('..'))
+        return false;
+    if (!CHANGE_ID_PATTERN.test(changeId))
+        return false;
+    return !hasUnsafePathShape(changeId);
+}
+export function isUnsafePathInput(input) {
+    return hasUnsafePathShape(input);
+}
+export function validateChangeIdOrThrow(changeId) {
+    if (!isValidChangeId(changeId)) {
+        throw new ChangeIdValidationError(changeId);
+    }
+}
+export class ChangeIdValidationError extends Error {
+    changeId;
+    constructor(changeId) {
+        super(`Invalid change-id: "${changeId}". Change-id must contain only letters, numbers, dots, underscores, or dashes, and must not be "." or "..".`);
+        this.name = 'ChangeIdValidationError';
+        this.changeId = changeId;
+    }
+}
+export function isUnsafeArtifactPath(path) {
+    return isUnsafePathInput(path);
+}
+export function buildArtifactRelativePath(changeId, ...segments) {
+    validateChangeIdOrThrow(changeId);
+    const joined = segments.map((segment) => normalizeForwardSlashes(segment)).join('/');
+    const candidatePath = `.peaks/changes/${changeId}/${joined}`;
+    if (isUnsafeArtifactPath(joined) || isUnsafeArtifactPath(candidatePath)) {
+        throw new ChangeIdValidationError(changeId);
+    }
+    return normalizeArtifactPath(candidatePath);
+}
+export function isPathInsideArtifactRoot(path, artifactRoot) {
+    if (!path || !artifactRoot)
+        return false;
+    const normalizedPath = normalizeArtifactPath(path);
+    const normalizedRoot = normalizeArtifactPath(artifactRoot);
+    return normalizedPath === normalizedRoot || normalizedPath.startsWith(`${normalizedRoot}/`);
+}

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

@@ -0,0 +1,6 @@
+export type SkillFrontmatter = {
+    name: string;
+    description: string;
+    [key: string]: string;
+};
+export declare function parseFrontmatter(markdown: string): SkillFrontmatter;

package/dist/src/shared/frontmatter.js

@@ -0,0 +1,47 @@
+export function parseFrontmatter(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    if (lines[0] !== '---') {
+        throw new Error('Missing YAML frontmatter opening marker');
+    }
+    const endIndex = lines.findIndex((line, index) => index > 0 && line === '---');
+    if (endIndex === -1) {
+        throw new Error('Missing YAML frontmatter closing marker');
+    }
+    const metadata = {};
+    const frontmatterLines = lines.slice(1, endIndex);
+    for (let index = 0; index < frontmatterLines.length; index += 1) {
+        const line = frontmatterLines[index];
+        if (!line || line.trim().length === 0) {
+            continue;
+        }
+        const blockMatch = line.match(/^([A-Za-z0-9_-]+):\s*[|>]\s*$/);
+        if (blockMatch?.[1]) {
+            const key = blockMatch[1];
+            const blockLines = [];
+            index += 1;
+            while (index < frontmatterLines.length) {
+                const blockLine = frontmatterLines[index];
+                if (blockLine && /^\S[^:]*:/.test(blockLine)) {
+                    index -= 1;
+                    break;
+                }
+                blockLines.push(blockLine?.replace(/^\s{2}/, '') ?? '');
+                index += 1;
+            }
+            metadata[key] = blockLines.join('\n').trim();
+            continue;
+        }
+        const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!match?.[1]) {
+            throw new Error(`Invalid frontmatter line: ${line}`);
+        }
+        metadata[match[1]] = (match[2] ?? '').trim().replace(/^['"]|['"]$/g, '');
+    }
+    if (!metadata.name) {
+        throw new Error('Missing required frontmatter field: name');
+    }
+    if (!metadata.description) {
+        throw new Error('Missing required frontmatter field: description');
+    }
+    return metadata;
+}

package/dist/src/shared/fs-utils.d.ts

@@ -0,0 +1,4 @@
+import type { Platform } from './platform.js';
+export declare function getDirectoryLinkType(targetPlatform?: Platform): 'junction' | 'dir';
+export declare function createDirectoryLinkSync(target: string, linkPath: string): void;
+export declare function readDirectoryLinkTarget(linkPath: string): string | null;

package/dist/src/shared/fs-utils.js

@@ -0,0 +1,16 @@
+import { symlinkSync as nodeSymlinkSync, readlinkSync } from 'node:fs';
+import { platform } from './platform.js';
+export function getDirectoryLinkType(targetPlatform = platform) {
+    return targetPlatform === 'win32' ? 'junction' : 'dir';
+}
+export function createDirectoryLinkSync(target, linkPath) {
+    nodeSymlinkSync(target, linkPath, getDirectoryLinkType());
+}
+export function readDirectoryLinkTarget(linkPath) {
+    try {
+        return readlinkSync(linkPath);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,4 @@
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function readText(path: string): Promise<string>;
+export declare function listDirectories(path: string): Promise<string[]>;
+export declare function isDirectory(path: string): Promise<boolean>;

package/dist/src/shared/fs.js

@@ -0,0 +1,26 @@
+import { access, readdir, readFile, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+export async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readText(path) {
+    return readFile(path, 'utf8');
+}
+export async function listDirectories(path) {
+    const entries = await readdir(path, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+export async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/shared/path-utils.d.ts

@@ -0,0 +1,13 @@
+import { type Platform } from './platform.js';
+export declare const SEP: "/" | "\\";
+export declare function normalizePath(p: string): string;
+export declare function pathsEqual(a: string, b: string): boolean;
+export declare function localPath(p: string, targetPlatform?: Platform): string;
+export declare function getTempDir(options?: {
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function isInsidePath(childPath: string, parentPath: string): boolean;
+export declare function isWindowsAbsolutePath(path: string): boolean;
+export declare function resolveInputPath(path: string): string;
+export declare function stableRealPath(path: string): string;
+export declare function stablePath(path: string): string;

package/dist/src/shared/path-utils.js

@@ -0,0 +1,56 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { isAbsolute, parse, relative, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { platform } from './platform.js';
+export const SEP = sep;
+const localPathConverters = {
+    win32: (p) => p.replace(/\//g, '\\'),
+    darwin: (p) => p,
+    linux: (p) => p
+};
+export function normalizePath(p) {
+    return p.replace(/\\/g, '/');
+}
+export function pathsEqual(a, b) {
+    return normalizePath(a) === normalizePath(b);
+}
+export function localPath(p, targetPlatform = platform) {
+    return localPathConverters[targetPlatform](p);
+}
+export function getTempDir(options) {
+    const env = options?.env ?? process.env;
+    if (env.TEMP)
+        return env.TEMP;
+    if (env.TMP)
+        return env.TMP;
+    return tmpdir();
+}
+export function isInsidePath(childPath, parentPath) {
+    const relativePath = relative(parentPath, childPath);
+    return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+export function isWindowsAbsolutePath(path) {
+    return /^[A-Za-z]:[\\/]/.test(path);
+}
+export function resolveInputPath(path) {
+    return isWindowsAbsolutePath(path) ? normalizePath(path) : resolve(path);
+}
+export function stableRealPath(path) {
+    return realpathSync(resolveInputPath(path));
+}
+export function stablePath(path) {
+    const resolvedPath = resolveInputPath(path);
+    if (existsSync(resolvedPath)) {
+        return stableRealPath(resolvedPath);
+    }
+    const parsedPath = parse(resolvedPath);
+    const missingSegments = [];
+    let currentPath = resolvedPath;
+    while (!existsSync(currentPath) && currentPath !== parsedPath.root) {
+        const parsedCurrent = parse(currentPath);
+        missingSegments.unshift(parsedCurrent.base);
+        currentPath = parsedCurrent.dir;
+    }
+    const realExistingPath = existsSync(currentPath) ? stableRealPath(currentPath) : parsedPath.root;
+    return resolve(realExistingPath, ...missingSegments);
+}

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

@@ -0,0 +1,6 @@
+export declare const repoRoot: string;
+export declare const skillsDir: string;
+export declare const schemasDir: string;
+export declare const templatesDir: string;
+export declare const requiredSkillNames: readonly ["peaks-solo", "peaks-prd", "peaks-ui", "peaks-rd", "peaks-qa", "peaks-sc", "peaks-txt"];
+export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json"];

package/dist/src/shared/paths.js

@@ -0,0 +1,40 @@
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function findRepoRoot(startPath) {
+    let currentPath = startPath;
+    while (currentPath !== dirname(currentPath)) {
+        if (existsSync(resolve(currentPath, 'package.json')) && existsSync(resolve(currentPath, 'skills'))) {
+            return currentPath;
+        }
+        currentPath = dirname(currentPath);
+    }
+    throw new Error(`Unable to locate Peaks repository root from ${startPath}`);
+}
+const currentFile = fileURLToPath(import.meta.url);
+export const repoRoot = findRepoRoot(dirname(currentFile));
+export const skillsDir = resolve(repoRoot, 'skills');
+export const schemasDir = resolve(repoRoot, 'schemas');
+export const templatesDir = resolve(repoRoot, 'templates');
+export const requiredSkillNames = [
+    'peaks-solo',
+    'peaks-prd',
+    'peaks-ui',
+    'peaks-rd',
+    'peaks-qa',
+    'peaks-sc',
+    'peaks-txt'
+];
+export const requiredSchemaFiles = [
+    'artifact-manifest.schema.json',
+    'context-capsule.schema.json',
+    'approval-record.schema.json',
+    'change-impact.schema.json',
+    'refactor-slice-spec.schema.json',
+    'artifact-retention-report.schema.json',
+    'capability-source.schema.json',
+    'capability-item.schema.json',
+    'capability-availability.schema.json',
+    'recommendation-plan.schema.json',
+    'artifact-workspace.schema.json'
+];

package/dist/src/shared/planner-response.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared response types for planner commands.
+ * These types ensure consistent error/status reporting across
+ * tech and RD swarm dry-run planner commands.
+ */
+export type WorkspaceUnavailableBehavior = 'preview' | 'blocked';
+export type ArtifactWorkspaceUnavailableResponse = {
+    available: false;
+    behavior: WorkspaceUnavailableBehavior;
+    reason: string;
+    nextActions: readonly string[];
+};
+export type ArtifactWorkspaceAvailableResponse<T> = {
+    available: true;
+    data: T;
+};
+export type ArtifactWorkspaceResponse<T> = ArtifactWorkspaceUnavailableResponse | ArtifactWorkspaceAvailableResponse<T>;
+export declare const WORKSPACE_UNAVAILABLE_NEXT_ACTIONS: readonly string[];
+export declare function makeUnavailableResponse(behavior: WorkspaceUnavailableBehavior, reason: string): ArtifactWorkspaceUnavailableResponse;
+export declare function makeAvailableResponse<T>(data: T): ArtifactWorkspaceAvailableResponse<T>;
+export declare function isUnavailableResponse<T>(resp: ArtifactWorkspaceResponse<T>): resp is ArtifactWorkspaceUnavailableResponse;