@fission-ai/openspec 0.17.1 → 0.18.0

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -0,0 +1,130 @@
+import { ArtifactGraph } from './graph.js';
+import type { CompletedSet } from './types.js';
+/**
+ * Error thrown when loading a template fails.
+ */
+export declare class TemplateLoadError extends Error {
+    readonly templatePath: string;
+    constructor(message: string, templatePath: string);
+}
+/**
+ * Change context containing graph, completion state, and metadata.
+ */
+export interface ChangeContext {
+    /** The artifact dependency graph */
+    graph: ArtifactGraph;
+    /** Set of completed artifact IDs */
+    completed: CompletedSet;
+    /** Schema name being used */
+    schemaName: string;
+    /** Change name */
+    changeName: string;
+    /** Path to the change directory */
+    changeDir: string;
+}
+/**
+ * Enriched instructions for creating an artifact.
+ */
+export interface ArtifactInstructions {
+    /** Change name */
+    changeName: string;
+    /** Artifact ID */
+    artifactId: string;
+    /** Schema name */
+    schemaName: string;
+    /** Full path to change directory */
+    changeDir: string;
+    /** Output path pattern (e.g., "proposal.md") */
+    outputPath: string;
+    /** Artifact description */
+    description: string;
+    /** Guidance on how to create this artifact (from schema instruction field) */
+    instruction: string | undefined;
+    /** Template content (structure to follow) */
+    template: string;
+    /** Dependencies with completion status and paths */
+    dependencies: DependencyInfo[];
+    /** Artifacts that become available after completing this one */
+    unlocks: string[];
+}
+/**
+ * Dependency information including path and description.
+ */
+export interface DependencyInfo {
+    /** Artifact ID */
+    id: string;
+    /** Whether the dependency is completed */
+    done: boolean;
+    /** Relative output path of the dependency (e.g., "proposal.md") */
+    path: string;
+    /** Description of the dependency artifact */
+    description: string;
+}
+/**
+ * Status of a single artifact in the workflow.
+ */
+export interface ArtifactStatus {
+    /** Artifact ID */
+    id: string;
+    /** Output path pattern */
+    outputPath: string;
+    /** Status: done, ready, or blocked */
+    status: 'done' | 'ready' | 'blocked';
+    /** Missing dependencies (only for blocked) */
+    missingDeps?: string[];
+}
+/**
+ * Formatted change status.
+ */
+export interface ChangeStatus {
+    /** Change name */
+    changeName: string;
+    /** Schema name */
+    schemaName: string;
+    /** Whether all artifacts are complete */
+    isComplete: boolean;
+    /** Artifact IDs required before apply phase (from schema's apply.requires) */
+    applyRequires: string[];
+    /** Status of each artifact */
+    artifacts: ArtifactStatus[];
+}
+/**
+ * Loads a template from a schema's templates directory.
+ *
+ * @param schemaName - Schema name (e.g., "spec-driven")
+ * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
+ * @returns The template content
+ * @throws TemplateLoadError if the template cannot be loaded
+ */
+export declare function loadTemplate(schemaName: string, templatePath: string): string;
+/**
+ * Loads change context combining graph and completion state.
+ *
+ * Schema resolution order:
+ * 1. Explicit schemaName parameter (if provided)
+ * 2. Schema from .openspec.yaml metadata (if exists in change directory)
+ * 3. Default 'spec-driven'
+ *
+ * @param projectRoot - Project root directory
+ * @param changeName - Change name
+ * @param schemaName - Optional schema name override. If not provided, auto-detected from metadata.
+ * @returns Change context with graph, completed set, and metadata
+ */
+export declare function loadChangeContext(projectRoot: string, changeName: string, schemaName?: string): ChangeContext;
+/**
+ * Generates enriched instructions for creating an artifact.
+ *
+ * @param context - Change context
+ * @param artifactId - Artifact ID to generate instructions for
+ * @returns Enriched artifact instructions
+ * @throws Error if artifact not found
+ */
+export declare function generateInstructions(context: ChangeContext, artifactId: string): ArtifactInstructions;
+/**
+ * Formats the status of all artifacts in a change.
+ *
+ * @param context - Change context
+ * @returns Formatted change status
+ */
+export declare function formatChangeStatus(context: ChangeContext): ChangeStatus;
+//# sourceMappingURL=instruction-loader.d.ts.map

package/dist/core/artifact-graph/instruction-loader.js

@@ -0,0 +1,173 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getSchemaDir, resolveSchema } from './resolver.js';
+import { ArtifactGraph } from './graph.js';
+import { detectCompleted } from './state.js';
+import { resolveSchemaForChange } from '../../utils/change-metadata.js';
+/**
+ * Error thrown when loading a template fails.
+ */
+export class TemplateLoadError extends Error {
+    templatePath;
+    constructor(message, templatePath) {
+        super(message);
+        this.templatePath = templatePath;
+        this.name = 'TemplateLoadError';
+    }
+}
+/**
+ * Loads a template from a schema's templates directory.
+ *
+ * @param schemaName - Schema name (e.g., "spec-driven")
+ * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
+ * @returns The template content
+ * @throws TemplateLoadError if the template cannot be loaded
+ */
+export function loadTemplate(schemaName, templatePath) {
+    const schemaDir = getSchemaDir(schemaName);
+    if (!schemaDir) {
+        throw new TemplateLoadError(`Schema '${schemaName}' not found`, templatePath);
+    }
+    const fullPath = path.join(schemaDir, 'templates', templatePath);
+    if (!fs.existsSync(fullPath)) {
+        throw new TemplateLoadError(`Template not found: ${fullPath}`, fullPath);
+    }
+    try {
+        return fs.readFileSync(fullPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new TemplateLoadError(`Failed to read template: ${ioError.message}`, fullPath);
+    }
+}
+/**
+ * Loads change context combining graph and completion state.
+ *
+ * Schema resolution order:
+ * 1. Explicit schemaName parameter (if provided)
+ * 2. Schema from .openspec.yaml metadata (if exists in change directory)
+ * 3. Default 'spec-driven'
+ *
+ * @param projectRoot - Project root directory
+ * @param changeName - Change name
+ * @param schemaName - Optional schema name override. If not provided, auto-detected from metadata.
+ * @returns Change context with graph, completed set, and metadata
+ */
+export function loadChangeContext(projectRoot, changeName, schemaName) {
+    const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
+    // Resolve schema: explicit > metadata > default
+    const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName);
+    const schema = resolveSchema(resolvedSchemaName);
+    const graph = ArtifactGraph.fromSchema(schema);
+    const completed = detectCompleted(graph, changeDir);
+    return {
+        graph,
+        completed,
+        schemaName: resolvedSchemaName,
+        changeName,
+        changeDir,
+    };
+}
+/**
+ * Generates enriched instructions for creating an artifact.
+ *
+ * @param context - Change context
+ * @param artifactId - Artifact ID to generate instructions for
+ * @returns Enriched artifact instructions
+ * @throws Error if artifact not found
+ */
+export function generateInstructions(context, artifactId) {
+    const artifact = context.graph.getArtifact(artifactId);
+    if (!artifact) {
+        throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
+    }
+    const template = loadTemplate(context.schemaName, artifact.template);
+    const dependencies = getDependencyInfo(artifact, context.graph, context.completed);
+    const unlocks = getUnlockedArtifacts(context.graph, artifactId);
+    return {
+        changeName: context.changeName,
+        artifactId: artifact.id,
+        schemaName: context.schemaName,
+        changeDir: context.changeDir,
+        outputPath: artifact.generates,
+        description: artifact.description,
+        instruction: artifact.instruction,
+        template,
+        dependencies,
+        unlocks,
+    };
+}
+/**
+ * Gets dependency info including paths and descriptions.
+ */
+function getDependencyInfo(artifact, graph, completed) {
+    return artifact.requires.map(id => {
+        const depArtifact = graph.getArtifact(id);
+        return {
+            id,
+            done: completed.has(id),
+            path: depArtifact?.generates ?? id,
+            description: depArtifact?.description ?? '',
+        };
+    });
+}
+/**
+ * Gets artifacts that become available after completing the given artifact.
+ */
+function getUnlockedArtifacts(graph, artifactId) {
+    const unlocks = [];
+    for (const artifact of graph.getAllArtifacts()) {
+        if (artifact.requires.includes(artifactId)) {
+            unlocks.push(artifact.id);
+        }
+    }
+    return unlocks.sort();
+}
+/**
+ * Formats the status of all artifacts in a change.
+ *
+ * @param context - Change context
+ * @returns Formatted change status
+ */
+export function formatChangeStatus(context) {
+    // Load schema to get apply phase configuration
+    const schema = resolveSchema(context.schemaName);
+    const applyRequires = schema.apply?.requires ?? schema.artifacts.map(a => a.id);
+    const artifacts = context.graph.getAllArtifacts();
+    const ready = new Set(context.graph.getNextArtifacts(context.completed));
+    const blocked = context.graph.getBlocked(context.completed);
+    const artifactStatuses = artifacts.map(artifact => {
+        if (context.completed.has(artifact.id)) {
+            return {
+                id: artifact.id,
+                outputPath: artifact.generates,
+                status: 'done',
+            };
+        }
+        if (ready.has(artifact.id)) {
+            return {
+                id: artifact.id,
+                outputPath: artifact.generates,
+                status: 'ready',
+            };
+        }
+        return {
+            id: artifact.id,
+            outputPath: artifact.generates,
+            status: 'blocked',
+            missingDeps: blocked[artifact.id] ?? [],
+        };
+    });
+    // Sort by build order for consistent output
+    const buildOrder = context.graph.getBuildOrder();
+    const orderMap = new Map(buildOrder.map((id, idx) => [id, idx]));
+    artifactStatuses.sort((a, b) => (orderMap.get(a.id) ?? 0) - (orderMap.get(b.id) ?? 0));
+    return {
+        changeName: context.changeName,
+        schemaName: context.schemaName,
+        isComplete: context.graph.isComplete(context.completed),
+        applyRequires,
+        artifacts: artifactStatuses,
+    };
+}
+//# sourceMappingURL=instruction-loader.js.map

package/dist/core/artifact-graph/resolver.d.ts

@@ -0,0 +1,61 @@
+import type { SchemaYaml } from './types.js';
+/**
+ * Error thrown when loading a schema fails.
+ */
+export declare class SchemaLoadError extends Error {
+    readonly schemaPath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, schemaPath: string, cause?: Error | undefined);
+}
+/**
+ * Gets the package's built-in schemas directory path.
+ * Uses import.meta.url to resolve relative to the current module.
+ */
+export declare function getPackageSchemasDir(): string;
+/**
+ * Gets the user's schema override directory path.
+ */
+export declare function getUserSchemasDir(): string;
+/**
+ * Resolves a schema name to its directory path.
+ *
+ * Resolution order:
+ * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @returns The path to the schema directory, or null if not found
+ */
+export declare function getSchemaDir(name: string): string | null;
+/**
+ * Resolves a schema name to a SchemaYaml object.
+ *
+ * Resolution order:
+ * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @returns The resolved schema object
+ * @throws Error if schema is not found in any location
+ */
+export declare function resolveSchema(name: string): SchemaYaml;
+/**
+ * Lists all available schema names.
+ * Combines user override and package built-in schemas.
+ */
+export declare function listSchemas(): string[];
+/**
+ * Schema info with metadata (name, description, artifacts).
+ */
+export interface SchemaInfo {
+    name: string;
+    description: string;
+    artifacts: string[];
+    source: 'package' | 'user';
+}
+/**
+ * Lists all available schemas with their descriptions and artifact lists.
+ * Useful for agent skills to present schema selection to users.
+ */
+export declare function listSchemasWithInfo(): SchemaInfo[];
+//# sourceMappingURL=resolver.d.ts.map

package/dist/core/artifact-graph/resolver.js

@@ -0,0 +1,187 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getGlobalDataDir } from '../global-config.js';
+import { parseSchema, SchemaValidationError } from './schema.js';
+/**
+ * Error thrown when loading a schema fails.
+ */
+export class SchemaLoadError extends Error {
+    schemaPath;
+    cause;
+    constructor(message, schemaPath, cause) {
+        super(message);
+        this.schemaPath = schemaPath;
+        this.cause = cause;
+        this.name = 'SchemaLoadError';
+    }
+}
+/**
+ * Gets the package's built-in schemas directory path.
+ * Uses import.meta.url to resolve relative to the current module.
+ */
+export function getPackageSchemasDir() {
+    const currentFile = fileURLToPath(import.meta.url);
+    // Navigate from dist/core/artifact-graph/ to package root's schemas/
+    return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
+}
+/**
+ * Gets the user's schema override directory path.
+ */
+export function getUserSchemasDir() {
+    return path.join(getGlobalDataDir(), 'schemas');
+}
+/**
+ * Resolves a schema name to its directory path.
+ *
+ * Resolution order:
+ * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @returns The path to the schema directory, or null if not found
+ */
+export function getSchemaDir(name) {
+    // 1. Check user override directory
+    const userDir = path.join(getUserSchemasDir(), name);
+    const userSchemaPath = path.join(userDir, 'schema.yaml');
+    if (fs.existsSync(userSchemaPath)) {
+        return userDir;
+    }
+    // 2. Check package built-in directory
+    const packageDir = path.join(getPackageSchemasDir(), name);
+    const packageSchemaPath = path.join(packageDir, 'schema.yaml');
+    if (fs.existsSync(packageSchemaPath)) {
+        return packageDir;
+    }
+    return null;
+}
+/**
+ * Resolves a schema name to a SchemaYaml object.
+ *
+ * Resolution order:
+ * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @returns The resolved schema object
+ * @throws Error if schema is not found in any location
+ */
+export function resolveSchema(name) {
+    // Normalize name (remove .yaml extension if provided)
+    const normalizedName = name.replace(/\.ya?ml$/, '');
+    const schemaDir = getSchemaDir(normalizedName);
+    if (!schemaDir) {
+        const availableSchemas = listSchemas();
+        throw new Error(`Schema '${normalizedName}' not found. Available schemas: ${availableSchemas.join(', ')}`);
+    }
+    const schemaPath = path.join(schemaDir, 'schema.yaml');
+    // Load and parse the schema
+    let content;
+    try {
+        content = fs.readFileSync(schemaPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new SchemaLoadError(`Failed to read schema at '${schemaPath}': ${ioError.message}`, schemaPath, ioError);
+    }
+    try {
+        return parseSchema(content);
+    }
+    catch (err) {
+        if (err instanceof SchemaValidationError) {
+            throw new SchemaLoadError(`Invalid schema at '${schemaPath}': ${err.message}`, schemaPath, err);
+        }
+        const parseError = err instanceof Error ? err : new Error(String(err));
+        throw new SchemaLoadError(`Failed to parse schema at '${schemaPath}': ${parseError.message}`, schemaPath, parseError);
+    }
+}
+/**
+ * Lists all available schema names.
+ * Combines user override and package built-in schemas.
+ */
+export function listSchemas() {
+    const schemas = new Set();
+    // Add package built-in schemas
+    const packageDir = getPackageSchemasDir();
+    if (fs.existsSync(packageDir)) {
+        for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    schemas.add(entry.name);
+                }
+            }
+        }
+    }
+    // Add user override schemas (may override package schemas)
+    const userDir = getUserSchemasDir();
+    if (fs.existsSync(userDir)) {
+        for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    schemas.add(entry.name);
+                }
+            }
+        }
+    }
+    return Array.from(schemas).sort();
+}
+/**
+ * Lists all available schemas with their descriptions and artifact lists.
+ * Useful for agent skills to present schema selection to users.
+ */
+export function listSchemasWithInfo() {
+    const schemas = [];
+    const seenNames = new Set();
+    // Add user override schemas first (they take precedence)
+    const userDir = getUserSchemasDir();
+    if (fs.existsSync(userDir)) {
+        for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    try {
+                        const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
+                        schemas.push({
+                            name: entry.name,
+                            description: schema.description || '',
+                            artifacts: schema.artifacts.map((a) => a.id),
+                            source: 'user',
+                        });
+                        seenNames.add(entry.name);
+                    }
+                    catch {
+                        // Skip invalid schemas
+                    }
+                }
+            }
+        }
+    }
+    // Add package built-in schemas (if not overridden)
+    const packageDir = getPackageSchemasDir();
+    if (fs.existsSync(packageDir)) {
+        for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
+            if (entry.isDirectory() && !seenNames.has(entry.name)) {
+                const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    try {
+                        const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
+                        schemas.push({
+                            name: entry.name,
+                            description: schema.description || '',
+                            artifacts: schema.artifacts.map((a) => a.id),
+                            source: 'package',
+                        });
+                    }
+                    catch {
+                        // Skip invalid schemas
+                    }
+                }
+            }
+        }
+    }
+    return schemas.sort((a, b) => a.name.localeCompare(b.name));
+}
+//# sourceMappingURL=resolver.js.map

package/dist/core/artifact-graph/schema.d.ts

@@ -0,0 +1,13 @@
+import { type SchemaYaml } from './types.js';
+export declare class SchemaValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Loads and validates an artifact schema from a YAML file.
+ */
+export declare function loadSchema(filePath: string): SchemaYaml;
+/**
+ * Parses and validates an artifact schema from YAML content.
+ */
+export declare function parseSchema(yamlContent: string): SchemaYaml;
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/artifact-graph/schema.js

@@ -0,0 +1,108 @@
+import * as fs from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { SchemaYamlSchema } from './types.js';
+export class SchemaValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SchemaValidationError';
+    }
+}
+/**
+ * Loads and validates an artifact schema from a YAML file.
+ */
+export function loadSchema(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseSchema(content);
+}
+/**
+ * Parses and validates an artifact schema from YAML content.
+ */
+export function parseSchema(yamlContent) {
+    const parsed = parseYaml(yamlContent);
+    // Validate with Zod
+    const result = SchemaYamlSchema.safeParse(parsed);
+    if (!result.success) {
+        const errors = result.error.issues.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
+        throw new SchemaValidationError(`Invalid schema: ${errors}`);
+    }
+    const schema = result.data;
+    // Check for duplicate artifact IDs
+    validateNoDuplicateIds(schema.artifacts);
+    // Check that all requires references are valid
+    validateRequiresReferences(schema.artifacts);
+    // Check for cycles
+    validateNoCycles(schema.artifacts);
+    return schema;
+}
+/**
+ * Validates that there are no duplicate artifact IDs.
+ */
+function validateNoDuplicateIds(artifacts) {
+    const seen = new Set();
+    for (const artifact of artifacts) {
+        if (seen.has(artifact.id)) {
+            throw new SchemaValidationError(`Duplicate artifact ID: ${artifact.id}`);
+        }
+        seen.add(artifact.id);
+    }
+}
+/**
+ * Validates that all `requires` references point to valid artifact IDs.
+ */
+function validateRequiresReferences(artifacts) {
+    const validIds = new Set(artifacts.map(a => a.id));
+    for (const artifact of artifacts) {
+        for (const req of artifact.requires) {
+            if (!validIds.has(req)) {
+                throw new SchemaValidationError(`Invalid dependency reference in artifact '${artifact.id}': '${req}' does not exist`);
+            }
+        }
+    }
+}
+/**
+ * Validates that there are no cyclic dependencies.
+ * Uses DFS to detect cycles and reports the full cycle path.
+ */
+function validateNoCycles(artifacts) {
+    const artifactMap = new Map(artifacts.map(a => [a.id, a]));
+    const visited = new Set();
+    const inStack = new Set();
+    const parent = new Map();
+    function dfs(id) {
+        visited.add(id);
+        inStack.add(id);
+        const artifact = artifactMap.get(id);
+        if (!artifact)
+            return null;
+        for (const dep of artifact.requires) {
+            if (!visited.has(dep)) {
+                parent.set(dep, id);
+                const cycle = dfs(dep);
+                if (cycle)
+                    return cycle;
+            }
+            else if (inStack.has(dep)) {
+                // Found a cycle - reconstruct the path
+                const cyclePath = [dep];
+                let current = id;
+                while (current !== dep) {
+                    cyclePath.unshift(current);
+                    current = parent.get(current);
+                }
+                cyclePath.unshift(dep);
+                return cyclePath.join(' → ');
+            }
+        }
+        inStack.delete(id);
+        return null;
+    }
+    for (const artifact of artifacts) {
+        if (!visited.has(artifact.id)) {
+            const cycle = dfs(artifact.id);
+            if (cycle) {
+                throw new SchemaValidationError(`Cyclic dependency detected: ${cycle}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/artifact-graph/state.d.ts

@@ -0,0 +1,12 @@
+import type { CompletedSet } from './types.js';
+import type { ArtifactGraph } from './graph.js';
+/**
+ * Detects which artifacts are completed by checking file existence in the change directory.
+ * Returns a Set of completed artifact IDs.
+ *
+ * @param graph - The artifact graph to check
+ * @param changeDir - The change directory to scan for files
+ * @returns Set of artifact IDs whose generated files exist
+ */
+export declare function detectCompleted(graph: ArtifactGraph, changeDir: string): CompletedSet;
+//# sourceMappingURL=state.d.ts.map