@fission-ai/openspec 0.17.2 → 0.18.0

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

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+// Artifact definition schema
+export const ArtifactSchema = z.object({
+    id: z.string().min(1, { error: 'Artifact ID is required' }),
+    generates: z.string().min(1, { error: 'generates field is required' }),
+    description: z.string(),
+    template: z.string().min(1, { error: 'template field is required' }),
+    instruction: z.string().optional(),
+    requires: z.array(z.string()).default([]),
+});
+// Apply phase configuration for schema-aware apply instructions
+export const ApplyPhaseSchema = z.object({
+    // Artifact IDs that must exist before apply is available
+    requires: z.array(z.string()).min(1, { error: 'At least one required artifact' }),
+    // Path to file with checkboxes for progress (relative to change dir), or null if no tracking
+    tracks: z.string().nullable().optional(),
+    // Custom guidance for the apply phase
+    instruction: z.string().optional(),
+});
+// Full schema YAML structure
+export const SchemaYamlSchema = z.object({
+    name: z.string().min(1, { error: 'Schema name is required' }),
+    version: z.number().int().positive({ error: 'Version must be a positive integer' }),
+    description: z.string().optional(),
+    artifacts: z.array(ArtifactSchema).min(1, { error: 'At least one artifact required' }),
+    // Optional apply phase configuration (for schema-aware apply instructions)
+    apply: ApplyPhaseSchema.optional(),
+});
+// Per-change metadata schema
+// Note: schema field is validated at parse time against available schemas
+// using a lazy import to avoid circular dependencies
+export const ChangeMetadataSchema = z.object({
+    // Required: which workflow schema this change uses
+    schema: z.string().min(1, { message: 'schema is required' }),
+    // Optional: creation timestamp (ISO date string)
+    created: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, {
+        message: 'created must be YYYY-MM-DD format',
+    })
+        .optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/core/converters/json-converter.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'fs';
 import path from 'path';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
 export class JsonConverter {
     convertSpecToJson(filePath) {
         const content = readFileSync(filePath, 'utf-8');
@@ -33,7 +34,7 @@ export class JsonConverter {
         return JSON.stringify(jsonChange, null, 2);
     }
     extractNameFromPath(filePath) {
-        const normalizedPath = filePath.replaceAll('\\', '/');
+        const normalizedPath = FileSystemUtils.toPosixPath(filePath);
         const parts = normalizedPath.split('/');
         for (let i = parts.length - 1; i >= 0; i--) {
             if (parts[i] === 'specs' || parts[i] === 'changes') {

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

@@ -1,5 +1,6 @@
 export declare const GLOBAL_CONFIG_DIR_NAME = "openspec";
 export declare const GLOBAL_CONFIG_FILE_NAME = "config.json";
+export declare const GLOBAL_DATA_DIR_NAME = "openspec";
 export interface GlobalConfig {
     featureFlags?: Record<string, boolean>;
 }
@@ -11,6 +12,15 @@ export interface GlobalConfig {
  * - Windows fallback: %APPDATA%/openspec/
  */
 export declare function getGlobalConfigDir(): string;
+/**
+ * Gets the global data directory path following XDG Base Directory Specification.
+ * Used for user data like schema overrides.
+ *
+ * - All platforms: $XDG_DATA_HOME/openspec/ if XDG_DATA_HOME is set
+ * - Unix/macOS fallback: ~/.local/share/openspec/
+ * - Windows fallback: %LOCALAPPDATA%/openspec/
+ */
+export declare function getGlobalDataDir(): string;
 /**
  * Gets the path to the global config file.
  */

package/dist/core/global-config.js

@@ -4,6 +4,7 @@ import * as os from 'node:os';
 // Constants
 export const GLOBAL_CONFIG_DIR_NAME = 'openspec';
 export const GLOBAL_CONFIG_FILE_NAME = 'config.json';
+export const GLOBAL_DATA_DIR_NAME = 'openspec';
 const DEFAULT_CONFIG = {
     featureFlags: {}
 };
@@ -33,6 +34,33 @@ export function getGlobalConfigDir() {
     // Unix/macOS fallback: ~/.config
     return path.join(os.homedir(), '.config', GLOBAL_CONFIG_DIR_NAME);
 }
+/**
+ * Gets the global data directory path following XDG Base Directory Specification.
+ * Used for user data like schema overrides.
+ *
+ * - All platforms: $XDG_DATA_HOME/openspec/ if XDG_DATA_HOME is set
+ * - Unix/macOS fallback: ~/.local/share/openspec/
+ * - Windows fallback: %LOCALAPPDATA%/openspec/
+ */
+export function getGlobalDataDir() {
+    // XDG_DATA_HOME takes precedence on all platforms when explicitly set
+    const xdgDataHome = process.env.XDG_DATA_HOME;
+    if (xdgDataHome) {
+        return path.join(xdgDataHome, GLOBAL_DATA_DIR_NAME);
+    }
+    const platform = os.platform();
+    if (platform === 'win32') {
+        // Windows: use %LOCALAPPDATA%
+        const localAppData = process.env.LOCALAPPDATA;
+        if (localAppData) {
+            return path.join(localAppData, GLOBAL_DATA_DIR_NAME);
+        }
+        // Fallback for Windows if LOCALAPPDATA is not set
+        return path.join(os.homedir(), 'AppData', 'Local', GLOBAL_DATA_DIR_NAME);
+    }
+    // Unix/macOS fallback: ~/.local/share
+    return path.join(os.homedir(), '.local', 'share', GLOBAL_DATA_DIR_NAME);
+}
 /**
  * Gets the path to the global config file.
  */

package/dist/core/index.d.ts

@@ -1,2 +1,2 @@
-export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, type GlobalConfig, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig } from './global-config.js';
+export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, type GlobalConfig, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -1,3 +1,3 @@
 // Core OpenSpec logic will be implemented here
-export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig } from './global-config.js';
+export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
 //# sourceMappingURL=index.js.map

package/dist/core/list.d.ts

@@ -1,4 +1,9 @@
+interface ListOptions {
+    sort?: 'recent' | 'name';
+    json?: boolean;
+}
 export declare class ListCommand {
-    execute(targetPath?: string, mode?: 'changes' | 'specs'): Promise<void>;
+    execute(targetPath?: string, mode?: 'changes' | 'specs', options?: ListOptions): Promise<void>;
 }
+export {};
 //# sourceMappingURL=list.d.ts.map

package/dist/core/list.js

@@ -4,8 +4,64 @@ import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progre
 import { readFileSync } from 'fs';
 import { join } from 'path';
 import { MarkdownParser } from './parsers/markdown-parser.js';
+/**
+ * Get the most recent modification time of any file in a directory (recursive).
+ * Falls back to the directory's own mtime if no files are found.
+ */
+async function getLastModified(dirPath) {
+    let latest = null;
+    async function walk(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else {
+                const stat = await fs.stat(fullPath);
+                if (latest === null || stat.mtime > latest) {
+                    latest = stat.mtime;
+                }
+            }
+        }
+    }
+    await walk(dirPath);
+    // If no files found, use the directory's own modification time
+    if (latest === null) {
+        const dirStat = await fs.stat(dirPath);
+        return dirStat.mtime;
+    }
+    return latest;
+}
+/**
+ * Format a date as relative time (e.g., "2 hours ago", "3 days ago")
+ */
+function formatRelativeTime(date) {
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffSecs = Math.floor(diffMs / 1000);
+    const diffMins = Math.floor(diffSecs / 60);
+    const diffHours = Math.floor(diffMins / 60);
+    const diffDays = Math.floor(diffHours / 24);
+    if (diffDays > 30) {
+        return date.toLocaleDateString();
+    }
+    else if (diffDays > 0) {
+        return `${diffDays}d ago`;
+    }
+    else if (diffHours > 0) {
+        return `${diffHours}h ago`;
+    }
+    else if (diffMins > 0) {
+        return `${diffMins}m ago`;
+    }
+    else {
+        return 'just now';
+    }
+}
 export class ListCommand {
-    async execute(targetPath = '.', mode = 'changes') {
+    async execute(targetPath = '.', mode = 'changes', options = {}) {
+        const { sort = 'recent', json = false } = options;
         if (mode === 'changes') {
             const changesDir = path.join(targetPath, 'openspec', 'changes');
             // Check if changes directory exists
@@ -21,21 +77,46 @@ export class ListCommand {
                 .filter(entry => entry.isDirectory() && entry.name !== 'archive')
                 .map(entry => entry.name);
             if (changeDirs.length === 0) {
-                console.log('No active changes found.');
+                if (json) {
+                    console.log(JSON.stringify({ changes: [] }));
+                }
+                else {
+                    console.log('No active changes found.');
+                }
                 return;
             }
             // Collect information about each change
             const changes = [];
             for (const changeDir of changeDirs) {
                 const progress = await getTaskProgressForChange(changesDir, changeDir);
+                const changePath = path.join(changesDir, changeDir);
+                const lastModified = await getLastModified(changePath);
                 changes.push({
                     name: changeDir,
                     completedTasks: progress.completed,
-                    totalTasks: progress.total
+                    totalTasks: progress.total,
+                    lastModified
                 });
             }
-            // Sort alphabetically by name
-            changes.sort((a, b) => a.name.localeCompare(b.name));
+            // Sort by preference (default: recent first)
+            if (sort === 'recent') {
+                changes.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+            }
+            else {
+                changes.sort((a, b) => a.name.localeCompare(b.name));
+            }
+            // JSON output for programmatic use
+            if (json) {
+                const jsonOutput = changes.map(c => ({
+                    name: c.name,
+                    completedTasks: c.completedTasks,
+                    totalTasks: c.totalTasks,
+                    lastModified: c.lastModified.toISOString(),
+                    status: c.totalTasks === 0 ? 'no-tasks' : c.completedTasks === c.totalTasks ? 'complete' : 'in-progress'
+                }));
+                console.log(JSON.stringify({ changes: jsonOutput }, null, 2));
+                return;
+            }
             // Display results
             console.log('Changes:');
             const padding = '  ';
@@ -43,7 +124,8 @@ export class ListCommand {
             for (const change of changes) {
                 const paddedName = change.name.padEnd(nameWidth);
                 const status = formatTaskStatus({ total: change.totalTasks, completed: change.completedTasks });
-                console.log(`${padding}${paddedName}     ${status}`);
+                const timeAgo = formatRelativeTime(change.lastModified);
+                console.log(`${padding}${paddedName}     ${status.padEnd(12)}  ${timeAgo}`);
             }
             return;
         }

package/dist/core/specs-apply.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Spec Application Logic
+ *
+ * Extracted from ArchiveCommand to enable standalone spec application.
+ * Applies delta specs from a change to main specs without archiving.
+ */
+export interface SpecUpdate {
+    source: string;
+    target: string;
+    exists: boolean;
+}
+export interface ApplyResult {
+    capability: string;
+    added: number;
+    modified: number;
+    removed: number;
+    renamed: number;
+}
+export interface SpecsApplyOutput {
+    changeName: string;
+    capabilities: ApplyResult[];
+    totals: {
+        added: number;
+        modified: number;
+        removed: number;
+        renamed: number;
+    };
+    noChanges: boolean;
+}
+/**
+ * Find all delta spec files that need to be applied from a change.
+ */
+export declare function findSpecUpdates(changeDir: string, mainSpecsDir: string): Promise<SpecUpdate[]>;
+/**
+ * Build an updated spec by applying delta operations.
+ * Returns the rebuilt content and counts of operations.
+ */
+export declare function buildUpdatedSpec(update: SpecUpdate, changeName: string): Promise<{
+    rebuilt: string;
+    counts: {
+        added: number;
+        modified: number;
+        removed: number;
+        renamed: number;
+    };
+}>;
+/**
+ * Write an updated spec to disk.
+ */
+export declare function writeUpdatedSpec(update: SpecUpdate, rebuilt: string, counts: {
+    added: number;
+    modified: number;
+    removed: number;
+    renamed: number;
+}): Promise<void>;
+/**
+ * Build a skeleton spec for new capabilities.
+ */
+export declare function buildSpecSkeleton(specFolderName: string, changeName: string): string;
+/**
+ * Apply all delta specs from a change to main specs.
+ *
+ * @param projectRoot - The project root directory
+ * @param changeName - The name of the change to apply
+ * @param options - Options for the operation
+ * @returns Result of the operation with counts
+ */
+export declare function applySpecs(projectRoot: string, changeName: string, options?: {
+    dryRun?: boolean;
+    skipValidation?: boolean;
+    silent?: boolean;
+}): Promise<SpecsApplyOutput>;
+//# sourceMappingURL=specs-apply.d.ts.map