@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/list.d.ts

@@ -0,0 +1,11 @@
+import type { RootOutput } from './root-selection.js';
+interface ListOptions {
+    sort?: 'recent' | 'name';
+    json?: boolean;
+    root?: RootOutput;
+}
+export declare class ListCommand {
+    execute(targetPath?: string, options?: ListOptions): Promise<void>;
+}
+export {};
+//# sourceMappingURL=list.d.ts.map

package/dist/core/list.js

@@ -0,0 +1,197 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
+import { describeNestedChange, findNestedChanges, } from '../utils/nested-change.js';
+import { changeParentDir, isChangeDirectoryName } from './change-layout.js';
+function isMissingPathError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+/**
+ * An entry that cannot be dated because it no longer resolves: it was removed
+ * after `readdir` listed it, or it is a symlink whose target is missing (an
+ * Emacs `.#file` lock) or that loops back on itself.
+ */
+function isUnresolvableEntryError(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return false;
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ELOOP';
+}
+async function readChangeDirectoryEntries(changesDir) {
+    try {
+        return await fs.readdir(changesDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return [];
+        throw error;
+    }
+}
+/**
+ * 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.
+ * Archived links use their own mtime: moving a change can break relative targets.
+ */
+async function getLastModified(dirPath, archived = false) {
+    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);
+            try {
+                if (entry.isDirectory()) {
+                    await walk(fullPath);
+                }
+                else {
+                    const stat = archived && entry.isSymbolicLink()
+                        ? await fs.lstat(fullPath)
+                        : await fs.stat(fullPath);
+                    if (latest === null || stat.mtime > latest) {
+                        latest = stat.mtime;
+                    }
+                }
+            }
+            catch (error) {
+                // Skip the one entry rather than fail the listing of every change.
+                if (!isUnresolvableEntryError(error))
+                    throw error;
+            }
+        }
+    }
+    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 = '.', options = {}) {
+        const { sort = 'recent', json = false, root } = options;
+        {
+            const changesDir = changeParentDir(targetPath);
+            const entries = await readChangeDirectoryEntries(changesDir);
+            const changeDirs = entries
+                .filter(entry => entry.isDirectory() && isChangeDirectoryName(entry.name))
+                .map(entry => ({ name: entry.name, parent: changesDir, archived: false }));
+            if (changeDirs.length === 0) {
+                if (json) {
+                    console.log(JSON.stringify({ changes: [], ...(root ? { root } : {}) }, null, 2));
+                }
+                else {
+                    console.log('No active changes found.');
+                }
+                return;
+            }
+            // Collect information about each change
+            const changes = [];
+            // A directory that only wraps nested change directories is still listed -
+            // hiding it would hide a real change whenever the probe is wrong - but it
+            // is listed as what it is, so the nesting stops failing silently (#1846).
+            const nestedFindings = await findNestedChanges(changesDir, changeDirs.map((changeDir) => changeDir.name));
+            const nestedByName = new Map(nestedFindings.map((finding) => [finding.name, finding]));
+            for (const changeDir of changeDirs) {
+                const progress = await getTaskProgressForChange(changeDir.parent, changeDir.name, targetPath);
+                const changePath = path.join(changeDir.parent, changeDir.name);
+                const lastModified = await getLastModified(changePath, changeDir.archived);
+                changes.push({
+                    name: changeDir.name,
+                    completedTasks: progress.completed,
+                    totalTasks: progress.total,
+                    lastModified,
+                    archived: changeDir.archived,
+                    ...(!changeDir.archived && nestedByName.has(changeDir.name)
+                        ? { nested: nestedByName.get(changeDir.name).nested }
+                        : {})
+                });
+            }
+            // 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',
+                    ...(c.nested ? { nested: c.nested } : {})
+                }));
+                // Additive: the entries keep their shape so existing consumers are
+                // unaffected, and the nesting is reported alongside them.
+                const warnings = nestedFindings.map((finding) => ({
+                    code: 'nested_change_directory',
+                    name: finding.name,
+                    nested: finding.nested,
+                    message: describeNestedChange(finding)
+                }));
+                console.log(JSON.stringify({
+                    changes: jsonOutput,
+                    ...(warnings.length > 0 ? { warnings } : {}),
+                    ...(root ? { root } : {})
+                }, null, 2));
+                return;
+            }
+            // Display results
+            const groups = [
+                { heading: 'Changes:', changes: changes.filter(change => !change.archived) },
+                { heading: 'Archived Changes:', changes: changes.filter(change => change.archived) }
+            ].filter(group => group.changes.length > 0);
+            for (const [index, group] of groups.entries()) {
+                if (index > 0)
+                    console.log('');
+                console.log(group.heading);
+                const padding = '  ';
+                const nameWidth = Math.max(...group.changes.map(c => c.name.length));
+                for (const change of group.changes) {
+                    const paddedName = change.name.padEnd(nameWidth);
+                    const status = change.nested
+                        ? 'not a change'
+                        : formatTaskStatus({ total: change.totalTasks, completed: change.completedTasks });
+                    const timeAgo = formatRelativeTime(change.lastModified);
+                    console.log(`${padding}${paddedName}     ${status.padEnd(12)}  ${timeAgo}`);
+                }
+            }
+            for (const finding of nestedFindings) {
+                console.log('');
+                console.log(`Warning: ${describeNestedChange(finding)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=list.js.map

package/dist/core/migration.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Migration Utilities
+ *
+ * One-time migration logic for existing projects when profile system is introduced.
+ * Called by both init and update commands before profile resolution.
+ */
+import { type AIToolOption } from './config.js';
+import { type Delivery, type GlobalConfig, type Profile } from './global-config.js';
+import { type FileView } from './file-view.js';
+export interface LegacyToolRoot {
+    /** Former tool root, e.g. '.kimi' */
+    root: string;
+    /**
+     * Whether leaving this root requires the user's say-so. False when the old
+     * product is gone and its directory is certainly dead. True when the old
+     * location may still be the live one for somebody.
+     */
+    needsConsent: boolean;
+    /** Migrations that need a freshly generated destination run afterward. */
+    timing?: 'before-generation' | 'after-generation';
+}
+/**
+ * Former tool roots whose FreeSpec-managed content belongs under the tool's
+ * current skillsDir. User files are never touched.
+ */
+export declare const LEGACY_TOOL_ROOTS: Record<string, LegacyToolRoot[]>;
+export interface LegacyToolMigration {
+    toolId: string;
+    /** Legacy tool root, e.g. '.windsurf' */
+    from: string;
+    /** Current tool root, e.g. '.devin' */
+    to: string;
+    /** Skill directories that moved, or would move */
+    skillDirs: number;
+    /** Command files that moved, or would move */
+    commandFiles: number;
+    /**
+     * FreeSpec-managed files left under the legacy root because the copy there
+     * differs materially from the one that survives, so it is reported rather
+     * than dropped.
+     */
+    keptInPlace: number;
+    /** Whether this move needs the user's consent first */
+    needsConsent: boolean;
+}
+/** One file a legacy-root migration would move or drop. */
+export interface LegacyMigrationFileOp {
+    toolId: string;
+    source: string;
+    destination: string;
+    disposition: 'move' | 'drop';
+    /** Whether an interactive run asks before this move */
+    needsConsent: boolean;
+}
+/**
+ * Reports the FreeSpec content sitting under each tool's legacy root, without
+ * moving anything. Callers use this to ask before a move that needs consent.
+ */
+export declare function findLegacyToolMigrations(projectPath: string, timing?: 'before-generation' | 'after-generation'): LegacyToolMigration[];
+/**
+ * Lists, file by file, what `migrateLegacyToolDirs` would move or drop, without
+ * touching anything. Consent-gated roots are included: a non-interactive run
+ * moves them without asking. `view` decides what already sits at each
+ * destination, so a dry run can plan against files it has not written.
+ */
+export declare function planLegacyToolMigrations(projectPath: string, timing: 'before-generation' | 'after-generation', toolIds: string[] | undefined, view: FileView): LegacyMigrationFileOp[];
+/**
+ * Moves FreeSpec-managed skill directories (freespec-*) and command files
+ * (freespec-*) from a tool's legacy root to its current one. When the destination
+ * already exists the legacy copy is removed instead. Legacy directories are
+ * deleted only when left empty, so user files under the old location — a
+ * hand-written Cascade workflow next to the generated ones — are preserved.
+ *
+ * @param projectPath - Project root
+ * @param toolIds - Restrict the move to these tools; omit to move every tool
+ *        whose legacy root needs no consent
+ */
+export declare function migrateLegacyToolDirs(projectPath: string, toolIds?: string[], timing?: 'before-generation' | 'after-generation'): LegacyToolMigration[];
+/**
+ * Summarizes what a migration moved, e.g. "6 skills and 6 commands".
+ */
+export declare function describeLegacyMigration(migration: LegacyToolMigration): string;
+/**
+ * Names FreeSpec-managed files the move deliberately left behind, so a user
+ * who customized one knows there are now two copies to reconcile.
+ */
+export declare function keptInPlaceNotice(migration: LegacyToolMigration): string | undefined;
+/**
+ * Whether a migration has anything to move, as opposed to only files left in
+ * place. Callers use this to avoid offering a move of nothing.
+ */
+export declare function hasMovableContent(migration: LegacyToolMigration): boolean;
+/**
+ * Explains why a consent-gated move is being offered, in the user's terms.
+ * Keyed by tool so the reason is specific rather than a generic "files moved".
+ */
+export declare function legacyMigrationNotice(migration: LegacyToolMigration): string;
+/**
+ * Scans installed workflow files across all detected tools and returns
+ * the union of installed workflow IDs.
+ */
+export declare function scanInstalledWorkflows(projectPath: string, tools: AIToolOption[], view?: FileView): string[];
+/**
+ * Performs one-time migration if the global config does not yet have a profile field.
+ * Called by both init and update before profile resolution.
+ *
+ * - If no profile field exists and workflows are installed: sets profile to 'custom'
+ *   with the detected workflows, preserving the user's existing setup.
+ * - If no profile field exists and no workflows are installed: no-op (defaults apply).
+ * - If profile field already exists: no-op.
+ */
+export declare function computeProfileMigration(projectPath: string, tools: AIToolOption[], view?: FileView): ProfileMigration | null;
+export type ProfileMigration = {
+    profile: Profile;
+    workflows: string[];
+    delivery?: Delivery;
+};
+/** The global config the one-time profile migration saves. */
+export declare function applyProfileMigration(migration: ProfileMigration): GlobalConfig;
+export declare function migrateIfNeeded(projectPath: string, tools: AIToolOption[]): void;
+//# sourceMappingURL=migration.d.ts.map