@clawplays/ospec-cli 0.3.4 → 0.3.5

package/README.md

@@ -37,6 +37,12 @@ OSpec is a document-driven workflow for AI-assisted development, helping you def
 npm install -g @clawplays/ospec-cli
 ```
 
+Update inside your project directory:
+
+```bash
+ospec update
+```
+
 ## Recommended Prompts
 
 Most teams only need 3 steps to use OSpec:
@@ -141,6 +147,7 @@ Archive notes:
 - run your project-specific deploy, test, and QA flow first
 - use `ospec verify` to confirm the active change is ready
 - use `ospec finalize` to rebuild indexes and archive the accepted change
+- new projects archive under `changes/archived/YYYY-MM/YYYY-MM-DD/<change-name>`; existing flat archives are reorganized by `ospec update`
 
 </details>
 

package/dist/cli.js

@@ -224,7 +224,7 @@ const services_1 = require("./services");
 
 
 
-const CLI_VERSION = '0.3.4';
+const CLI_VERSION = '0.3.5';
 
 function showInitUsage() {
     console.log('Usage: ospec init [root-dir] [--summary "..."] [--tech-stack node,react] [--architecture "..."] [--document-language en-US|zh-CN|ja-JP|ar]');

package/dist/commands/ArchiveCommand.js

@@ -180,7 +180,7 @@ class ArchiveCommand extends BaseCommand_1.BaseCommand {
                     this.success('Change is ready to archive');
                     return;
                 }
-                const archivePath = await this.performArchive(targetPath, projectRoot, featureState);
+                const archivePath = await this.performArchive(targetPath, projectRoot, featureState, config);
                 this.success(`Change archived to ${archivePath}`);
                 return archivePath;
             }
@@ -194,11 +194,10 @@ class ArchiveCommand extends BaseCommand_1.BaseCommand {
             throw error;
         }
     }
-    async performArchive(targetPath, projectRoot, featureState) {
+    async performArchive(targetPath, projectRoot, featureState, config) {
         const archivedRoot = path.join(projectRoot, constants_1.DIR_NAMES.CHANGES, constants_1.DIR_NAMES.ARCHIVED);
         await services_1.services.fileService.ensureDir(archivedRoot);
-        const archiveDirName = await this.resolveArchiveDirName(archivedRoot, featureState.feature);
-        const archivePath = path.join(archivedRoot, archiveDirName);
+        const archivePath = await this.resolveArchivePath(archivedRoot, featureState.feature, config);
         const nextState = {
             ...featureState,
             status: 'archived',
@@ -222,9 +221,29 @@ class ArchiveCommand extends BaseCommand_1.BaseCommand {
         proposal.data.status = status;
         await services_1.services.fileService.writeFile(proposalPath, gray_matter_1.default.stringify(proposal.content, proposal.data));
     }
-    async resolveArchiveDirName(archivedRoot, featureName) {
-        const datePrefix = new Date().toISOString().slice(0, 10);
-        const baseName = `${datePrefix}-${featureName}`;
+    async resolveArchivePath(archivedRoot, featureName, config) {
+        const archiveLayout = config?.archive?.layout === 'month-day' ? 'month-day' : 'flat';
+        const archiveDate = this.getLocalArchiveDateParts();
+        if (archiveLayout === 'month-day') {
+            const archiveDayRoot = path.join(archivedRoot, archiveDate.month, archiveDate.day);
+            await services_1.services.fileService.ensureDir(archiveDayRoot);
+            const archiveLeafName = await this.resolveArchiveLeafName(archiveDayRoot, featureName);
+            return path.join(archiveDayRoot, archiveLeafName);
+        }
+        const archiveDirName = await this.resolveLegacyArchiveDirName(archivedRoot, archiveDate.day, featureName);
+        return path.join(archivedRoot, archiveDirName);
+    }
+    async resolveArchiveLeafName(archiveDayRoot, featureName) {
+        let candidate = featureName;
+        let index = 2;
+        while (await services_1.services.fileService.exists(path.join(archiveDayRoot, candidate))) {
+            candidate = `${featureName}-${index}`;
+            index += 1;
+        }
+        return candidate;
+    }
+    async resolveLegacyArchiveDirName(archivedRoot, archiveDay, featureName) {
+        const baseName = `${archiveDay}-${featureName}`;
         let candidate = baseName;
         let index = 2;
         while (await services_1.services.fileService.exists(path.join(archivedRoot, candidate))) {
@@ -233,6 +252,16 @@ class ArchiveCommand extends BaseCommand_1.BaseCommand {
         }
         return candidate;
     }
+    getLocalArchiveDateParts() {
+        const now = new Date();
+        const year = String(now.getFullYear());
+        const monthNumber = String(now.getMonth() + 1).padStart(2, '0');
+        const dayNumber = String(now.getDate()).padStart(2, '0');
+        return {
+            month: `${year}-${monthNumber}`,
+            day: `${year}-${monthNumber}-${dayNumber}`,
+        };
+    }
     toRelativePath(rootDir, targetPath) {
         return path.relative(rootDir, targetPath).replace(/\\/g, '/');
     }

package/dist/commands/UpdateCommand.js

@@ -18,8 +18,14 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
         const protocolResult = await services_1.services.projectService.syncProtocolGuidance(targetPath);
         const toolingResult = await this.syncProjectTooling(targetPath, protocolResult.documentLanguage);
         const pluginResult = await this.syncEnabledPluginAssets(targetPath);
+        const archiveResult = await this.syncArchiveLayout(targetPath);
         const skillResult = await this.syncInstalledSkills();
-        const refreshedFiles = [...protocolResult.refreshedFiles, ...toolingResult.refreshedFiles, ...pluginResult.refreshedFiles];
+        const refreshedFiles = Array.from(new Set([
+            ...protocolResult.refreshedFiles,
+            ...toolingResult.refreshedFiles,
+            ...pluginResult.refreshedFiles,
+            ...(archiveResult.configSaved ? ['.skillrc'] : []),
+        ]));
         const createdFiles = [...protocolResult.createdFiles, ...toolingResult.createdFiles, ...pluginResult.createdFiles];
         const skippedFiles = [...protocolResult.skippedFiles, ...toolingResult.skippedFiles, ...pluginResult.skippedFiles];
         this.success(`Updated OSpec assets for ${protocolResult.projectName}`);
@@ -40,8 +46,14 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
         if (pluginResult.configSaved) {
             this.info('  plugin config normalized: .skillrc');
         }
-        this.info('  note: update refreshes protocol docs, tooling, hooks, managed skills, and managed assets for already-enabled plugins');
-        this.info('  note: it does not enable, disable, or migrate existing changes automatically');
+        if (archiveResult.configSaved) {
+            this.info('  archive layout normalized: .skillrc');
+        }
+        if (archiveResult.migratedChanges.length > 0) {
+            this.info(`  archived changes migrated: ${archiveResult.migratedChanges.length}`);
+        }
+        this.info('  note: update refreshes protocol docs, tooling, hooks, managed skills, managed assets for already-enabled plugins, and the archive layout when needed');
+        this.info('  note: it does not enable, disable, or migrate active or queued changes automatically');
     }
     async syncProjectTooling(rootDir, documentLanguage) {
         const toolingPaths = [
@@ -222,6 +234,100 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
         }
         return { createdFiles, skippedFiles };
     }
+    async syncArchiveLayout(rootDir) {
+        const rawConfig = await services_1.services.fileService.readJSON((0, path_1.join)(rootDir, '.skillrc'));
+        const config = await services_1.services.configManager.loadConfig(rootDir);
+        const nextConfig = JSON.parse(JSON.stringify(config));
+        const archivedRoot = (0, path_1.join)(rootDir, 'changes', 'archived');
+        const migratedChanges = [];
+        if (await services_1.services.fileService.exists(archivedRoot)) {
+            const entryNames = (await services_1.services.fileService.readDir(archivedRoot)).sort((left, right) => left.localeCompare(right));
+            for (const entryName of entryNames) {
+                const entryPath = (0, path_1.join)(archivedRoot, entryName);
+                const stat = await services_1.services.fileService.stat(entryPath);
+                if (!stat.isDirectory()) {
+                    continue;
+                }
+                const parsed = this.parseLegacyArchiveDirName(entryName);
+                if (!parsed) {
+                    continue;
+                }
+                const archivedState = await this.readArchivedChangeState(entryPath);
+                if (!archivedState) {
+                    continue;
+                }
+                const archiveDayRoot = (0, path_1.join)(archivedRoot, parsed.month, parsed.day);
+                await services_1.services.fileService.ensureDir(archiveDayRoot);
+                const targetPath = await this.resolveArchiveMigrationTarget(archiveDayRoot, archivedState.feature);
+                await services_1.services.fileService.move(entryPath, targetPath);
+                migratedChanges.push({
+                    from: `changes/archived/${entryName}`,
+                    to: this.toRelativePath(rootDir, targetPath),
+                });
+            }
+        }
+        let configSaved = false;
+        if (nextConfig.archive?.layout !== 'month-day') {
+            nextConfig.archive = {
+                ...(nextConfig.archive || {}),
+                layout: 'month-day',
+            };
+            await services_1.services.configManager.saveConfig(rootDir, nextConfig);
+            configSaved = true;
+        }
+        else if (!rawConfig?.archive || rawConfig.archive.layout !== 'month-day') {
+            await services_1.services.configManager.saveConfig(rootDir, nextConfig);
+            configSaved = true;
+        }
+        return {
+            configSaved,
+            migratedChanges,
+        };
+    }
+    parseLegacyArchiveDirName(entryName) {
+        const match = /^(\d{4}-\d{2}-\d{2})-(.+)$/.exec(entryName);
+        if (!match) {
+            return null;
+        }
+        return {
+            month: match[1].slice(0, 7),
+            day: match[1],
+            leafName: match[2],
+        };
+    }
+    async resolveArchiveMigrationTarget(archiveDayRoot, leafName) {
+        let candidate = leafName;
+        let index = 2;
+        while (await services_1.services.fileService.exists((0, path_1.join)(archiveDayRoot, candidate))) {
+            candidate = `${leafName}-${index}`;
+            index += 1;
+        }
+        return (0, path_1.join)(archiveDayRoot, candidate);
+    }
+    async readArchivedChangeState(entryPath) {
+        const statePath = (0, path_1.join)(entryPath, 'state.json');
+        if (!(await services_1.services.fileService.exists(statePath))) {
+            return null;
+        }
+        try {
+            const state = await services_1.services.fileService.readJSON(statePath);
+            if (typeof state?.feature !== 'string' || state.feature.trim().length === 0) {
+                return null;
+            }
+            if (state.status !== 'archived') {
+                return null;
+            }
+            return {
+                feature: state.feature.trim(),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    toRelativePath(rootDir, targetPath) {
+        return (0, path_1.relative)(rootDir, targetPath).replace(/\\/g, '/');
+    }
     getManagedSkillNames() {
         return ['ospec', 'ospec-change'];
     }

package/dist/core/types.d.ts

@@ -89,6 +89,9 @@ export interface CheckpointPluginConfig {
         auto_pass_stitch_review: boolean;
     };
 }
+export interface ArchiveConfig {
+    layout: 'flat' | 'month-day';
+}
 export interface SkillrcConfig {
     version: string;
     mode: ProjectMode;
@@ -104,6 +107,7 @@ export interface SkillrcConfig {
         include?: string[];
         exclude?: string[];
     };
+    archive?: ArchiveConfig;
     plugins?: {
         stitch?: StitchPluginConfig;
         checkpoint?: CheckpointPluginConfig;

package/dist/services/ConfigManager.js

@@ -81,6 +81,9 @@ class ConfigManager {
             index: {
                 exclude: ['node_modules/**', 'dist/**', '*.test.*'],
             },
+            archive: {
+                layout: 'month-day',
+            },
             plugins: this.createDefaultPluginsConfig(),
             workflow,
         };
@@ -345,6 +348,7 @@ class ConfigManager {
     }
     normalizeConfig(config) {
         const mode = ['lite', 'standard', 'full'].includes(config.mode) ? config.mode : 'full';
+        const archive = config.archive && typeof config.archive === 'object' ? config.archive : {};
         const hooks = config.hooks || {
             'pre-commit': true,
             'post-merge': true,
@@ -370,6 +374,9 @@ class ConfigManager {
             version: config.version === '3.0' ? '4.0' : config.version,
             mode,
             documentLanguage: this.normalizeDocumentLanguage(config.documentLanguage),
+            archive: {
+                layout: archive.layout === 'month-day' ? 'month-day' : 'flat',
+            },
             hooks: {
                 ...normalizedHooks,
                 ...(legacyWarnDefaults

package/dist/services/ProjectService.js

@@ -4385,71 +4385,15 @@ class ProjectService {
 
 
 
-        const archivedRoot = path_1.default.join(projectRoot, constants_1.DIR_NAMES.CHANGES, constants_1.DIR_NAMES.ARCHIVED);
-
-
-
-
-
-
-
-        await this.fileService.ensureDir(archivedRoot);
-
-
-
-
-
-
-
-        const datePrefix = new Date().toISOString().slice(0, 10);
-
-
+        const config = await this.configManager.loadConfig(projectRoot);
 
 
 
 
 
-        const baseName = `${datePrefix}-${featureState.feature}`;
-
-
-
-
-
-
-
-        let archiveDirName = baseName;
-
-
-
-
-
-
-
-        let archiveIndex = 2;
-
-
 
 
-
-
-
-        while (await this.fileService.exists(path_1.default.join(archivedRoot, archiveDirName))) {
-
-
-
-
-
-
-
-            archiveDirName = `${baseName}-${archiveIndex}`;
-
-
-
-
-
-
-
-            archiveIndex += 1;
+        const archivedRoot = path_1.default.join(projectRoot, constants_1.DIR_NAMES.CHANGES, constants_1.DIR_NAMES.ARCHIVED);
 
 
 
@@ -4457,7 +4401,7 @@ class ProjectService {
 
 
 
-        }
+        await this.fileService.ensureDir(archivedRoot);
 
 
 
@@ -4465,7 +4409,7 @@ class ProjectService {
 
 
 
-        const archivePath = path_1.default.join(archivedRoot, archiveDirName);
+        const archivePath = await this.resolveArchivePath(archivedRoot, featureState.feature, config);
 
 
 
@@ -12449,6 +12393,252 @@ ${formatSuggestion()}
 
 
 
+    async resolveArchivePath(archivedRoot, featureName, config) {
+
+
+
+
+
+        const archiveLayout = config?.archive?.layout === 'month-day' ? 'month-day' : 'flat';
+
+
+
+
+
+        const archiveDate = this.getLocalArchiveDateParts();
+
+
+
+
+
+        if (archiveLayout === 'month-day') {
+
+
+
+
+
+            const archiveDayRoot = path_1.default.join(archivedRoot, archiveDate.month, archiveDate.day);
+
+
+
+
+
+            await this.fileService.ensureDir(archiveDayRoot);
+
+
+
+
+
+            const archiveLeafName = await this.resolveArchiveLeafName(archiveDayRoot, featureName);
+
+
+
+
+
+            return path_1.default.join(archiveDayRoot, archiveLeafName);
+
+
+
+
+
+        }
+
+
+
+
+
+        const archiveDirName = await this.resolveLegacyArchiveDirName(archivedRoot, archiveDate.day, featureName);
+
+
+
+
+
+        return path_1.default.join(archivedRoot, archiveDirName);
+
+
+
+
+
+    }
+
+
+
+
+
+    async resolveArchiveLeafName(archiveDayRoot, featureName) {
+
+
+
+
+
+        let candidate = featureName;
+
+
+
+
+
+        let archiveIndex = 2;
+
+
+
+
+
+        while (await this.fileService.exists(path_1.default.join(archiveDayRoot, candidate))) {
+
+
+
+
+
+            candidate = `${featureName}-${archiveIndex}`;
+
+
+
+
+
+            archiveIndex += 1;
+
+
+
+
+
+        }
+
+
+
+
+
+        return candidate;
+
+
+
+
+
+    }
+
+
+
+
+
+    async resolveLegacyArchiveDirName(archivedRoot, archiveDay, featureName) {
+
+
+
+
+
+        const baseName = `${archiveDay}-${featureName}`;
+
+
+
+
+
+        let candidate = baseName;
+
+
+
+
+
+        let archiveIndex = 2;
+
+
+
+
+
+        while (await this.fileService.exists(path_1.default.join(archivedRoot, candidate))) {
+
+
+
+
+
+            candidate = `${baseName}-${archiveIndex}`;
+
+
+
+
+
+            archiveIndex += 1;
+
+
+
+
+
+        }
+
+
+
+
+
+        return candidate;
+
+
+
+
+
+    }
+
+
+
+
+
+    getLocalArchiveDateParts() {
+
+
+
+
+
+        const now = new Date();
+
+
+
+
+
+        const year = String(now.getFullYear());
+
+
+
+
+
+        const monthNumber = String(now.getMonth() + 1).padStart(2, '0');
+
+
+
+
+
+        const dayNumber = String(now.getDate()).padStart(2, '0');
+
+
+
+
+
+        return {
+
+
+
+
+
+            month: `${year}-${monthNumber}`,
+
+
+
+
+
+            day: `${year}-${monthNumber}-${dayNumber}`,
+
+
+
+
+
+        };
+
+
+
+
+
+    }
+
+
+
+
+
     toRelativePath(rootDir, filePath) {
 
 

package/dist/services/RunService.js

@@ -350,13 +350,59 @@ class RunService {
         if (!(await this.fileService.exists(archivedDir))) {
             return null;
         }
+        const candidatePaths = await this.listArchivedChangeDirectories(archivedDir);
+        const matches = [];
+        for (const candidatePath of candidatePaths) {
+            const statePath = path_1.default.join(candidatePath, constants_1.FILE_NAMES.STATE);
+            if (!(await this.fileService.exists(statePath))) {
+                continue;
+            }
+            try {
+                const state = await this.fileService.readJSON(statePath);
+                if (state?.feature === changeName && state?.status === 'archived') {
+                    matches.push(this.toArchivedRelativePath(archivedDir, candidatePath));
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return matches.sort().at(-1) || null;
+    }
+    async listArchivedChangeDirectories(archivedDir) {
         const entries = await fs_extra_1.default.readdir(archivedDir, { withFileTypes: true });
-        const matched = entries
-            .filter(entry => entry.isDirectory() && entry.name.endsWith(`-${changeName}`))
-            .map(entry => entry.name)
-            .sort()
-            .at(-1);
-        return matched ? `changes/archived/${matched}` : null;
+        const candidates = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const entryPath = path_1.default.join(archivedDir, entry.name);
+            if (/^\d{4}-\d{2}-\d{2}-.+/.test(entry.name)) {
+                candidates.push(entryPath);
+                continue;
+            }
+            if (!/^\d{4}-\d{2}$/.test(entry.name)) {
+                continue;
+            }
+            const dayEntries = await fs_extra_1.default.readdir(entryPath, { withFileTypes: true });
+            for (const dayEntry of dayEntries) {
+                if (!dayEntry.isDirectory() || !/^\d{4}-\d{2}-\d{2}$/.test(dayEntry.name)) {
+                    continue;
+                }
+                const dayPath = path_1.default.join(entryPath, dayEntry.name);
+                const changeEntries = await fs_extra_1.default.readdir(dayPath, { withFileTypes: true });
+                for (const changeEntry of changeEntries) {
+                    if (changeEntry.isDirectory()) {
+                        candidates.push(path_1.default.join(dayPath, changeEntry.name));
+                    }
+                }
+            }
+        }
+        return candidates;
+    }
+    toArchivedRelativePath(archivedDir, candidatePath) {
+        const relativePath = path_1.default.relative(archivedDir, candidatePath).replace(/\\/g, '/');
+        return `changes/archived/${relativePath}`;
     }
     async ensureRunDirectories(rootDir) {
         await Promise.all([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawplays/ospec-cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "CLI tool for enforcing ospec workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",