gmc-openspec 1.0.0

package/dist/core/planning-home.js

@@ -0,0 +1,124 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getWorkspaceChangesDir, getWorkspaceSharedStatePath, parseWorkspaceSharedState, } from './workspace/index.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+const REPO_DEFAULT_SCHEMA = 'spec-driven';
+const WORKSPACE_DEFAULT_SCHEMA = 'workspace-planning';
+function pathExistsAsDirectory(candidatePath) {
+    try {
+        return fs.statSync(candidatePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function pathExistsAsFile(candidatePath) {
+    try {
+        return fs.statSync(candidatePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function getSearchStartDirectory(startPath) {
+    const resolved = path.resolve(startPath);
+    try {
+        const stats = fs.statSync(resolved);
+        const searchStart = stats.isDirectory() ? resolved : path.dirname(resolved);
+        return FileSystemUtils.canonicalizeExistingPath(searchStart);
+    }
+    catch {
+        return resolved;
+    }
+}
+function findNearestAncestor(startPath, predicate) {
+    let currentDir = getSearchStartDirectory(startPath);
+    while (true) {
+        if (predicate(currentDir)) {
+            return FileSystemUtils.canonicalizeExistingPath(currentDir);
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+export function findWorkspacePlanningRootSync(startPath = process.cwd()) {
+    return findNearestAncestor(startPath, (dirPath) => pathExistsAsFile(getWorkspaceSharedStatePath(dirPath)));
+}
+export function findRepoPlanningRootSync(startPath = process.cwd()) {
+    return findNearestAncestor(startPath, (dirPath) => pathExistsAsDirectory(path.join(dirPath, 'openspec')));
+}
+function isSameOrDescendant(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function countPathSegments(candidatePath) {
+    return path.resolve(candidatePath).split(path.sep).filter(Boolean).length;
+}
+function isWindowsLikePath(candidatePath) {
+    return /^[A-Za-z]:[\\/]/.test(candidatePath) || candidatePath.startsWith('\\\\');
+}
+function relativePlanningPath(fromPath, toPath) {
+    if (isWindowsLikePath(fromPath) || isWindowsLikePath(toPath)) {
+        return path.win32.relative(path.win32.normalize(fromPath), path.win32.normalize(toPath));
+    }
+    return path.posix.relative(fromPath.replace(/\\/g, '/'), toPath.replace(/\\/g, '/'));
+}
+function readWorkspaceSharedStateSync(workspaceRoot) {
+    try {
+        return parseWorkspaceSharedState(fs.readFileSync(getWorkspaceSharedStatePath(workspaceRoot), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function workspacePlanningHome(workspaceRoot) {
+    const sharedState = readWorkspaceSharedStateSync(workspaceRoot);
+    return {
+        kind: 'workspace',
+        root: workspaceRoot,
+        changesDir: getWorkspaceChangesDir(workspaceRoot),
+        defaultSchema: WORKSPACE_DEFAULT_SCHEMA,
+        workspace: {
+            name: sharedState?.name ?? path.basename(workspaceRoot),
+            links: Object.keys(sharedState?.links ?? {}).sort((a, b) => a.localeCompare(b)),
+        },
+    };
+}
+function repoPlanningHome(repoRoot) {
+    return {
+        kind: 'repo',
+        root: repoRoot,
+        changesDir: path.join(repoRoot, 'openspec', 'changes'),
+        defaultSchema: REPO_DEFAULT_SCHEMA,
+    };
+}
+export function resolveCurrentPlanningHomeSync(options = {}) {
+    const startPath = options.startPath ?? process.cwd();
+    const searchStart = getSearchStartDirectory(startPath);
+    const workspaceRoot = findWorkspacePlanningRootSync(searchStart);
+    const repoRoot = findRepoPlanningRootSync(searchStart);
+    if (workspaceRoot && isSameOrDescendant(workspaceRoot, searchStart)) {
+        if (!repoRoot || countPathSegments(workspaceRoot) >= countPathSegments(repoRoot)) {
+            return workspacePlanningHome(workspaceRoot);
+        }
+    }
+    if (repoRoot) {
+        return repoPlanningHome(repoRoot);
+    }
+    if (options.allowImplicitRepoRoot === false) {
+        throw new Error('No OpenSpec planning home found from the current directory.');
+    }
+    return repoPlanningHome(FileSystemUtils.canonicalizeExistingPath(searchStart));
+}
+export function getChangeDir(planningHome, changeName) {
+    return FileSystemUtils.joinPath(planningHome.changesDir, changeName);
+}
+export function formatChangeLocation(planningHome, changeName) {
+    const changeDir = getChangeDir(planningHome, changeName);
+    const relative = relativePlanningPath(planningHome.root, changeDir);
+    return relative.length > 0 ? relative : changeDir;
+}
+//# sourceMappingURL=planning-home.js.map

package/dist/core/profile-sync-drift.d.ts

@@ -0,0 +1,38 @@
+import type { Delivery } from './global-config.js';
+import { ALL_WORKFLOWS } from './profiles.js';
+type WorkflowId = (typeof ALL_WORKFLOWS)[number];
+/**
+ * Maps workflow IDs to their skill directory names.
+ */
+export declare const WORKFLOW_TO_SKILL_DIR: Record<WorkflowId, string>;
+/**
+ * Checks whether a tool has at least one generated OpenSpec command file.
+ */
+export declare function toolHasAnyConfiguredCommand(projectPath: string, toolId: string): boolean;
+/**
+ * Returns tools with at least one generated command file on disk.
+ */
+export declare function getCommandConfiguredTools(projectPath: string): string[];
+/**
+ * Returns tools that are configured via either skills or commands.
+ */
+export declare function getConfiguredToolsForProfileSync(projectPath: string): string[];
+/**
+ * Detects if a single tool has profile/delivery drift against the desired state.
+ *
+ * This function covers:
+ * - required artifacts missing for selected workflows
+ * - artifacts that should not exist for the selected delivery mode
+ * - artifacts for workflows that were deselected from the current profile
+ */
+export declare function hasToolProfileOrDeliveryDrift(projectPath: string, toolId: string, desiredWorkflows: readonly string[], delivery: Delivery): boolean;
+/**
+ * Returns configured tools that currently need a profile/delivery sync.
+ */
+export declare function getToolsNeedingProfileSync(projectPath: string, desiredWorkflows: readonly string[], delivery: Delivery, configuredTools?: readonly string[]): string[];
+/**
+ * Detects whether the current project has any profile/delivery drift.
+ */
+export declare function hasProjectConfigDrift(projectPath: string, desiredWorkflows: readonly string[], delivery: Delivery): boolean;
+export {};
+//# sourceMappingURL=profile-sync-drift.d.ts.map

package/dist/core/profile-sync-drift.js

@@ -0,0 +1,200 @@
+import path from 'path';
+import * as fs from 'fs';
+import { AI_TOOLS } from './config.js';
+import { ALL_WORKFLOWS } from './profiles.js';
+import { CommandAdapterRegistry } from './command-generation/index.js';
+import { COMMAND_IDS, getConfiguredTools } from './shared/index.js';
+/**
+ * Maps workflow IDs to their skill directory names.
+ */
+export const WORKFLOW_TO_SKILL_DIR = {
+    'explore': 'openspec-explore',
+    'new': 'openspec-new-change',
+    'continue': 'openspec-continue-change',
+    'apply': 'openspec-apply-change',
+    'ff': 'openspec-ff-change',
+    'sync': 'openspec-sync-specs',
+    'archive': 'openspec-archive-change',
+    'bulk-archive': 'openspec-bulk-archive-change',
+    'verify': 'openspec-verify-change',
+    'onboard': 'openspec-onboard',
+    'propose': 'openspec-propose',
+};
+function toKnownWorkflows(workflows) {
+    return workflows.filter((workflow) => ALL_WORKFLOWS.includes(workflow));
+}
+/**
+ * Checks whether a tool has at least one generated OpenSpec command file.
+ */
+export function toolHasAnyConfiguredCommand(projectPath, toolId) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    if (!adapter)
+        return false;
+    for (const commandId of COMMAND_IDS) {
+        const cmdPath = adapter.getFilePath(commandId);
+        const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+        if (fs.existsSync(fullPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Returns tools with at least one generated command file on disk.
+ */
+export function getCommandConfiguredTools(projectPath) {
+    return AI_TOOLS
+        .filter((tool) => {
+        if (!tool.skillsDir)
+            return false;
+        const toolDir = path.join(projectPath, tool.skillsDir);
+        try {
+            return fs.statSync(toolDir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((tool) => tool.value)
+        .filter((toolId) => toolHasAnyConfiguredCommand(projectPath, toolId));
+}
+/**
+ * Returns tools that are configured via either skills or commands.
+ */
+export function getConfiguredToolsForProfileSync(projectPath) {
+    const skillConfigured = getConfiguredTools(projectPath);
+    const commandConfigured = getCommandConfiguredTools(projectPath);
+    return [...new Set([...skillConfigured, ...commandConfigured])];
+}
+/**
+ * Detects if a single tool has profile/delivery drift against the desired state.
+ *
+ * This function covers:
+ * - required artifacts missing for selected workflows
+ * - artifacts that should not exist for the selected delivery mode
+ * - artifacts for workflows that were deselected from the current profile
+ */
+export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkflows, delivery) {
+    const tool = AI_TOOLS.find((t) => t.value === toolId);
+    if (!tool?.skillsDir)
+        return false;
+    const knownDesiredWorkflows = toKnownWorkflows(desiredWorkflows);
+    const desiredWorkflowSet = new Set(knownDesiredWorkflows);
+    const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
+    const adapter = CommandAdapterRegistry.get(toolId);
+    const shouldGenerateSkills = delivery !== 'commands';
+    const shouldGenerateCommands = delivery !== 'skills';
+    if (shouldGenerateSkills) {
+        for (const workflow of knownDesiredWorkflows) {
+            const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
+            const skillFile = path.join(skillsDir, dirName, 'SKILL.md');
+            if (!fs.existsSync(skillFile)) {
+                return true;
+            }
+        }
+        // Deselecting workflows in a profile should trigger sync.
+        for (const workflow of ALL_WORKFLOWS) {
+            if (desiredWorkflowSet.has(workflow))
+                continue;
+            const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
+            const skillDir = path.join(skillsDir, dirName);
+            if (fs.existsSync(skillDir)) {
+                return true;
+            }
+        }
+    }
+    else {
+        for (const workflow of ALL_WORKFLOWS) {
+            const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
+            const skillDir = path.join(skillsDir, dirName);
+            if (fs.existsSync(skillDir)) {
+                return true;
+            }
+        }
+    }
+    if (shouldGenerateCommands && adapter) {
+        for (const workflow of knownDesiredWorkflows) {
+            const cmdPath = adapter.getFilePath(workflow);
+            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            if (!fs.existsSync(fullPath)) {
+                return true;
+            }
+        }
+        // Deselecting workflows in a profile should trigger sync.
+        for (const workflow of ALL_WORKFLOWS) {
+            if (desiredWorkflowSet.has(workflow))
+                continue;
+            const cmdPath = adapter.getFilePath(workflow);
+            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            if (fs.existsSync(fullPath)) {
+                return true;
+            }
+        }
+    }
+    else if (!shouldGenerateCommands && adapter) {
+        for (const workflow of ALL_WORKFLOWS) {
+            const cmdPath = adapter.getFilePath(workflow);
+            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            if (fs.existsSync(fullPath)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Returns configured tools that currently need a profile/delivery sync.
+ */
+export function getToolsNeedingProfileSync(projectPath, desiredWorkflows, delivery, configuredTools) {
+    const tools = configuredTools ? [...new Set(configuredTools)] : getConfiguredToolsForProfileSync(projectPath);
+    return tools.filter((toolId) => hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkflows, delivery));
+}
+function getInstalledWorkflowsForTool(projectPath, toolId, options) {
+    const tool = AI_TOOLS.find((t) => t.value === toolId);
+    if (!tool?.skillsDir)
+        return [];
+    const installed = new Set();
+    const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
+    if (options.includeSkills) {
+        for (const workflow of ALL_WORKFLOWS) {
+            const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
+            const skillFile = path.join(skillsDir, dirName, 'SKILL.md');
+            if (fs.existsSync(skillFile)) {
+                installed.add(workflow);
+            }
+        }
+    }
+    if (options.includeCommands) {
+        const adapter = CommandAdapterRegistry.get(toolId);
+        if (adapter) {
+            for (const workflow of ALL_WORKFLOWS) {
+                const cmdPath = adapter.getFilePath(workflow);
+                const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+                if (fs.existsSync(fullPath)) {
+                    installed.add(workflow);
+                }
+            }
+        }
+    }
+    return [...installed];
+}
+/**
+ * Detects whether the current project has any profile/delivery drift.
+ */
+export function hasProjectConfigDrift(projectPath, desiredWorkflows, delivery) {
+    const configuredTools = getConfiguredToolsForProfileSync(projectPath);
+    if (getToolsNeedingProfileSync(projectPath, desiredWorkflows, delivery, configuredTools).length > 0) {
+        return true;
+    }
+    const desiredSet = new Set(toKnownWorkflows(desiredWorkflows));
+    const includeSkills = delivery !== 'commands';
+    const includeCommands = delivery !== 'skills';
+    for (const toolId of configuredTools) {
+        const installed = getInstalledWorkflowsForTool(projectPath, toolId, { includeSkills, includeCommands });
+        if (installed.some((workflow) => !desiredSet.has(workflow))) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=profile-sync-drift.js.map

package/dist/core/profiles.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Profile System
+ *
+ * Defines workflow profiles that control which workflows are installed.
+ * Profiles determine WHICH workflows; delivery (in global config) determines HOW.
+ */
+import type { Profile } from './global-config.js';
+/**
+ * Core workflows included in the 'core' profile.
+ * These provide the streamlined experience for new users.
+ */
+export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "apply", "sync", "archive"];
+/**
+ * All available workflows in the system.
+ */
+export declare const ALL_WORKFLOWS: readonly ["propose", "explore", "new", "continue", "apply", "ff", "sync", "archive", "bulk-archive", "verify", "onboard"];
+export type WorkflowId = (typeof ALL_WORKFLOWS)[number];
+export type CoreWorkflowId = (typeof CORE_WORKFLOWS)[number];
+/**
+ * Resolves which workflows should be active for a given profile configuration.
+ *
+ * - 'core' profile always returns CORE_WORKFLOWS
+ * - 'custom' profile returns the provided customWorkflows, or empty array if not provided
+ */
+export declare function getProfileWorkflows(profile: Profile, customWorkflows?: string[]): readonly string[];
+//# sourceMappingURL=profiles.d.ts.map

package/dist/core/profiles.js

@@ -0,0 +1,40 @@
+/**
+ * Profile System
+ *
+ * Defines workflow profiles that control which workflows are installed.
+ * Profiles determine WHICH workflows; delivery (in global config) determines HOW.
+ */
+/**
+ * Core workflows included in the 'core' profile.
+ * These provide the streamlined experience for new users.
+ */
+export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'sync', 'archive'];
+/**
+ * All available workflows in the system.
+ */
+export const ALL_WORKFLOWS = [
+    'propose',
+    'explore',
+    'new',
+    'continue',
+    'apply',
+    'ff',
+    'sync',
+    'archive',
+    'bulk-archive',
+    'verify',
+    'onboard',
+];
+/**
+ * Resolves which workflows should be active for a given profile configuration.
+ *
+ * - 'core' profile always returns CORE_WORKFLOWS
+ * - 'custom' profile returns the provided customWorkflows, or empty array if not provided
+ */
+export function getProfileWorkflows(profile, customWorkflows) {
+    if (profile === 'custom') {
+        return customWorkflows ?? [];
+    }
+    return CORE_WORKFLOWS;
+}
+//# sourceMappingURL=profiles.js.map

package/dist/core/project-config.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+/**
+ * Zod schema for project configuration.
+ *
+ * Purpose:
+ * 1. Documentation - clearly defines the config file structure
+ * 2. Type safety - TypeScript infers ProjectConfig type from schema
+ * 3. Runtime validation - uses safeParse() for resilient field-by-field validation
+ *
+ * Why Zod over manual validation:
+ * - Helps understand OpenSpec's data interfaces at a glance
+ * - Single source of truth for type and validation
+ * - Consistent with other OpenSpec schemas
+ */
+export declare const ProjectConfigSchema: z.ZodObject<{
+    schema: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+/**
+ * Read and parse openspec/config.yaml from project root.
+ * Uses resilient parsing - validates each field independently using Zod safeParse.
+ * Returns null if file doesn't exist.
+ * Returns partial config if some fields are invalid (with warnings).
+ *
+ * Performance note (Jan 2025):
+ * Benchmarks showed direct file reads are fast enough without caching:
+ * - Typical config (1KB): ~0.5ms per read
+ * - Large config (50KB): ~1.6ms per read
+ * - Missing config: ~0.01ms per read
+ * Config is read 1-2 times per command (schema resolution + instruction loading),
+ * adding ~1-3ms total overhead. Caching would add complexity (mtime checks,
+ * invalidation logic) for negligible benefit. Direct reads also ensure config
+ * changes are reflected immediately without stale cache issues.
+ *
+ * @param projectRoot - The root directory of the project (where `openspec/` lives)
+ * @returns Parsed config or null if file doesn't exist
+ */
+export declare function readProjectConfig(projectRoot: string): ProjectConfig | null;
+/**
+ * Validate artifact IDs in rules against a schema's artifacts.
+ * Called during instruction loading (when schema is known).
+ * Returns warnings for unknown artifact IDs.
+ *
+ * @param rules - The rules object from config
+ * @param validArtifactIds - Set of valid artifact IDs from the schema
+ * @param schemaName - Name of the schema for error messages
+ * @returns Array of warning messages for unknown artifact IDs
+ */
+export declare function validateConfigRules(rules: Record<string, string[]>, validArtifactIds: Set<string>, schemaName: string): string[];
+/**
+ * Suggest valid schema names when user provides invalid schema.
+ * Uses fuzzy matching to find similar names.
+ *
+ * @param invalidSchemaName - The invalid schema name from config
+ * @param availableSchemas - List of available schemas with their type (built-in or project-local)
+ * @returns Error message with suggestions and available schemas
+ */
+export declare function suggestSchemas(invalidSchemaName: string, availableSchemas: {
+    name: string;
+    isBuiltIn: boolean;
+}[]): string;
+//# sourceMappingURL=project-config.d.ts.map