@kbdavis07/openspec 1.5.0-nov.1

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,201 @@
+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',
+    'update': 'openspec-update-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", "update", "sync", "archive"];
+/**
+ * All available workflows in the system.
+ */
+export declare const ALL_WORKFLOWS: readonly ["propose", "explore", "new", "continue", "apply", "update", "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,41 @@
+/**
+ * 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', 'update', 'sync', 'archive'];
+/**
+ * All available workflows in the system.
+ */
+export const ALL_WORKFLOWS = [
+    'propose',
+    'explore',
+    'new',
+    'continue',
+    'apply',
+    'update',
+    '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,107 @@
+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>>>;
+    store: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Normalized in-memory shape of a referenced store declaration. */
+export interface DeclarationEntry {
+    id: string;
+    /** Clone source rendered into onboarding fixes. */
+    remote?: string;
+}
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema> & {
+    references?: DeclarationEntry[];
+};
+export declare const MAX_CONTEXT_SIZE: number;
+/**
+ * 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;
+export interface StorePointerRead {
+    /** The declared store id, when present and a string. */
+    value?: string;
+    /** Set when the pointer cannot be trusted: the config file could not be
+     * read as YAML, or the store key is present but not a string. An empty
+     * or comments-only config is NOT malformed - it simply has no pointer. */
+    malformed?: 'unparseable' | 'non_string';
+    /** Absolute path of the config file actually read, or null when none exists. */
+    filePath: string | null;
+}
+/**
+ * Warning-silent targeted read of the `store:` pointer. Used by root
+ * resolution (which must not re-emit the resilient parser's field
+ * warnings) and by `openspec init`'s pointer guard. Unlike
+ * `readProjectConfig`, a malformed value is REPORTED, not dropped —
+ * a dropped pointer would silently flip where work lands.
+ */
+export declare function readStorePointer(projectRoot: string): StorePointerRead;
+/** Shared .yaml/.yml probe used by readProjectConfig and readStorePointer. */
+export declare function resolveConfigFilePath(projectRoot: string): string | null;
+/** Human rendering of a malformed pointer reason, shared by every surface. */
+export declare function storePointerProblem(reason: 'unparseable' | 'non_string'): string;
+export interface OpenSpecDirClassification {
+    /** True when openspec/specs or openspec/changes exists as a directory. */
+    hasPlanningShape: boolean;
+    pointer: StorePointerRead;
+}
+/**
+ * One classification for "real root vs config-only pointer dir", shared
+ * by root resolution and the init pointer guard so they can never
+ * disagree (slice 3.2).
+ */
+export declare function classifyOpenSpecDir(projectRoot: string): OpenSpecDirClassification;
+//# sourceMappingURL=project-config.d.ts.map