@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/update-plan.js

@@ -0,0 +1,390 @@
+/**
+ * Update Plan
+ *
+ * The write seam `update` uses for every file it generates or removes.
+ *
+ * A real run forwards to the filesystem. A dry run records what the same call
+ * would have done and writes nothing, so the preview and the real update come
+ * from one code path instead of two descriptions of it.
+ */
+import path from 'path';
+import * as fs from 'fs';
+import os from 'os';
+import { FileSystemUtils } from '../utils/file-system.js';
+export const realFileOps = {
+    async writeFile(filePath, content) {
+        await FileSystemUtils.writeFile(filePath, content);
+    },
+    async removeFile(filePath) {
+        await fs.promises.unlink(filePath);
+    },
+    async removeDirectory(dirPath) {
+        await fs.promises.rm(dirPath, { recursive: true, force: true });
+    },
+    async removeEmptyDirectory(dirPath) {
+        await fs.promises.rmdir(dirPath);
+    },
+};
+export class UpdatePlanRecorder {
+    projectPath;
+    notes = [];
+    failures = [];
+    /**
+     * The tree as the real update would have it so far: absolute path to planned
+     * content, a moved directory, or null once planned away (a removed directory
+     * takes everything under it). Steps that read what an earlier step left
+     * behind read this through `view`.
+     */
+    staged = new Map();
+    /** Every file path the plan has touched, with the tool that touched it last. */
+    touched = new Map();
+    constructor(projectPath) {
+        this.projectPath = projectPath;
+    }
+    async writeFile(filePath, content, tool) {
+        const target = path.resolve(filePath);
+        this.probeWrite(target);
+        this.stage(target, content, tool);
+    }
+    async removeFile(filePath, tool) {
+        const target = path.resolve(filePath);
+        this.probeRemove(target);
+        this.stage(target, null, tool);
+    }
+    async removeEmptyDirectory(dirPath) {
+        // An empty directory holds no file, so there is nothing to list.
+        this.staged.set(path.resolve(dirPath), null);
+    }
+    async removeDirectory(dirPath, tool) {
+        const target = path.resolve(dirPath);
+        // A symlinked skills directory - what a dotfile manager leaves behind - is
+        // removed as the link itself: `fs.rm` with `recursive` unlinks it and never
+        // touches the tree it points at, so the link is the one entry that goes.
+        let stats = null;
+        try {
+            stats = fs.lstatSync(target);
+        }
+        catch {
+            stats = null;
+        }
+        if (stats?.isSymbolicLink()) {
+            this.stage(target, null, tool);
+            return;
+        }
+        // Otherwise every file under it goes - on disk, and any the plan put there.
+        // Each is cleared on its own: a file's own entry outranks its directory's.
+        for (const filePath of this.filesUnder(target))
+            this.stage(filePath, null, tool);
+        this.staged.set(target, null);
+    }
+    /**
+     * A rename, as the legacy-root migration makes it: whatever the entry is
+     * moves, a directory with everything in it.
+     */
+    async moveFile(source, destination, tool) {
+        const from = path.resolve(source);
+        const to = path.resolve(destination);
+        this.probeCreatableIn(path.dirname(to));
+        if (this.entryKind(from).kind === 'directory') {
+            if (this.entryKind(to).kind !== 'missing') {
+                throw errnoError('ENOTEMPTY', 'directory not empty', 'rename', to);
+            }
+            const files = this.filesUnder(from);
+            const contents = files.map((filePath) => [filePath, this.view.read(filePath)]);
+            for (const filePath of files)
+                this.stage(filePath, null, tool);
+            this.staged.set(from, null);
+            this.staged.set(to, STAGED_DIRECTORY);
+            for (const [filePath, content] of contents) {
+                this.stage(path.join(to, path.relative(from, filePath)), content, tool);
+            }
+            return;
+        }
+        const content = this.view.read(from);
+        this.probeWrite(to);
+        this.probeRemove(from);
+        this.stage(from, null, tool);
+        this.stage(to, content, tool);
+    }
+    /**
+     * The tree with every planned write, move and removal applied. A path the
+     * plan has not touched answers exactly as the disk does.
+     */
+    view = {
+        exists: (filePath) => this.entryKind(path.resolve(filePath)).kind !== 'missing',
+        isDirectory: (filePath) => this.entryKind(path.resolve(filePath)).kind === 'directory',
+        read: (filePath) => {
+            const target = path.resolve(filePath);
+            const staged = this.stagedEntry(target);
+            if (staged === undefined)
+                return fs.readFileSync(target, 'utf-8');
+            if (staged === null)
+                throw errnoError('ENOENT', 'no such file or directory', 'open', target);
+            if (staged === STAGED_DIRECTORY) {
+                throw errnoError('EISDIR', 'illegal operation on a directory', 'read', target);
+            }
+            return staged;
+        },
+    };
+    addNote(code, message) {
+        if (this.notes.some((note) => note.code === code))
+            return;
+        this.notes.push({ code, message });
+    }
+    addFailure(tool, error) {
+        this.failures.push({ tool, error });
+    }
+    /**
+     * Each touched path, compared as it is on disk now with how the plan leaves
+     * it. A file written and then removed, or rewritten with the bytes it
+     * already had, is no change at all.
+     */
+    getPlan() {
+        const byPath = new Map();
+        for (const [filePath, tool] of this.touched) {
+            const before = originalEntry(filePath);
+            const after = this.stagedEntry(filePath);
+            if (after === undefined || after === STAGED_DIRECTORY)
+                continue;
+            let action;
+            if (after === null) {
+                if (before !== undefined)
+                    action = 'delete';
+            }
+            else if (before === undefined) {
+                action = 'add';
+            }
+            else if (before !== after) {
+                action = 'update';
+            }
+            if (!action)
+                continue;
+            const displayPath = this.toDisplayPath(filePath);
+            byPath.set(displayPath, { path: displayPath, action, tool });
+        }
+        const changes = [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+        return { changes, notes: [...this.notes], failures: [...this.failures] };
+    }
+    stage(target, entry, tool) {
+        this.staged.set(target, entry);
+        this.touched.set(target, tool);
+    }
+    /**
+     * What the plan has put at a path: content, a moved directory, null once
+     * planned away, or undefined when the plan has not touched it.
+     */
+    stagedEntry(target) {
+        for (let current = target;; current = path.dirname(current)) {
+            const staged = this.staged.get(current);
+            if (staged === null)
+                return null;
+            if (staged !== undefined && current === target)
+                return staged;
+            if (path.dirname(current) === current)
+                return undefined;
+        }
+    }
+    /** Whether the plan has put any file or directory below `directory`. */
+    hasStagedDescendant(directory) {
+        const prefix = directory.endsWith(path.sep) ? directory : directory + path.sep;
+        for (const key of this.staged.keys()) {
+            if (!key.startsWith(prefix))
+                continue;
+            const entry = this.stagedEntry(key);
+            if (entry !== null && entry !== undefined)
+                return true;
+        }
+        return false;
+    }
+    /** Files under a directory in the tree as planned: those on disk, and those the plan added. */
+    filesUnder(directory) {
+        const files = new Set();
+        for (const filePath of listFilesRecursively(directory)) {
+            if (this.stagedEntry(filePath) !== null)
+                files.add(filePath);
+        }
+        const prefix = directory + path.sep;
+        for (const key of this.staged.keys()) {
+            if (key.startsWith(prefix) && typeof this.stagedEntry(key) === 'string')
+                files.add(key);
+        }
+        return [...files];
+    }
+    /**
+     * What is at a path in the tree as planned, and whether that is what is on
+     * disk (so its permissions are real).
+     */
+    entryKind(target) {
+        const staged = this.stagedEntry(target);
+        if (staged === null) {
+            // Removed, but the plan may have written into it again since.
+            return this.hasStagedDescendant(target)
+                ? { kind: 'directory', onDisk: false }
+                : { kind: 'missing', onDisk: false };
+        }
+        if (staged === STAGED_DIRECTORY)
+            return { kind: 'directory', onDisk: false };
+        if (typeof staged === 'string') {
+            return { kind: 'file', onDisk: fs.existsSync(target) };
+        }
+        try {
+            return { kind: fs.statSync(target).isDirectory() ? 'directory' : 'file', onDisk: true };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                throw error;
+        }
+        return this.hasStagedDescendant(target)
+            ? { kind: 'directory', onDisk: false }
+            : { kind: 'missing', onDisk: false };
+    }
+    /**
+     * Fails the way the real write would, without writing: a directory where the
+     * file belongs, a file where one of its directories belongs, or no
+     * permission. Recording the write instead would plan past the point where
+     * the real update stops for this tool, listing files it never writes.
+     */
+    probeWrite(target) {
+        const entry = this.entryKind(target);
+        if (entry.kind === 'directory') {
+            throw errnoError('EISDIR', 'illegal operation on a directory', 'open', target);
+        }
+        if (entry.kind === 'file') {
+            if (entry.onDisk)
+                fs.accessSync(target, fs.constants.W_OK);
+            return;
+        }
+        this.probeCreatableIn(path.dirname(target));
+    }
+    /** Fails the way unlinking the file would. */
+    probeRemove(target) {
+        const entry = this.entryKind(target);
+        if (entry.kind === 'directory') {
+            throw errnoError('EISDIR', 'illegal operation on a directory', 'unlink', target);
+        }
+        if (entry.kind === 'file' && entry.onDisk) {
+            fs.accessSync(path.dirname(target), fs.constants.W_OK);
+        }
+    }
+    /**
+     * The nearest existing ancestor has to be a directory the update can create
+     * entries in; anything it would create below that starts out empty.
+     */
+    probeCreatableIn(directory) {
+        for (let current = directory;; current = path.dirname(current)) {
+            const entry = this.entryKind(current);
+            if (entry.kind === 'file') {
+                throw errnoError('ENOTDIR', 'not a directory', 'mkdir', current);
+            }
+            if (entry.kind === 'directory') {
+                if (entry.onDisk)
+                    fs.accessSync(current, fs.constants.W_OK);
+                return;
+            }
+            if (path.dirname(current) === current)
+                return;
+        }
+    }
+    toDisplayPath(filePath) {
+        const absolute = path.resolve(filePath);
+        const relative = path.relative(this.projectPath, absolute);
+        if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+            return FileSystemUtils.toPosixPath(relative);
+        }
+        // Same home resolution the skill paths use, so a global skill is named
+        // against the home the generator wrote it to.
+        const home = process.env.USERPROFILE ?? process.env.HOME ?? os.homedir();
+        const fromHome = path.relative(home, absolute);
+        if (fromHome && !fromHome.startsWith('..') && !path.isAbsolute(fromHome)) {
+            return `~/${FileSystemUtils.toPosixPath(fromHome)}`;
+        }
+        return FileSystemUtils.toPosixPath(absolute);
+    }
+}
+/** Marks a path the plan has moved a whole directory to. */
+const STAGED_DIRECTORY = Symbol('staged directory');
+/**
+ * A path as it is on disk now: a file's content (read through a symlink that
+ * points at a file), a symlink to anything else as an entry of its own, or
+ * undefined when absent or a directory.
+ *
+ * The file is judged on the handle it is read from, so nothing can swap it
+ * between the check and the read. O_NONBLOCK keeps a FIFO from hanging the
+ * plan; Windows has no such flag and no FIFOs to worry about.
+ */
+function originalEntry(target) {
+    let descriptor;
+    try {
+        descriptor = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+        if (fs.fstatSync(descriptor).isFile()) {
+            return fs.readFileSync(descriptor, 'utf-8');
+        }
+    }
+    catch {
+        // Missing, a dangling link, or a directory on a platform that refuses to
+        // open one: decided below.
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+    try {
+        return `symlink:${fs.readlinkSync(target)}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** An error shaped like the one Node's own fs call would throw. */
+function errnoError(code, description, syscall, target) {
+    return Object.assign(new Error(`${code}: ${description}, ${syscall} '${target}'`), {
+        code,
+        syscall,
+        path: target,
+    });
+}
+function listFilesRecursively(dirPath) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listFilesRecursively(full));
+        }
+        else {
+            files.push(full);
+        }
+    }
+    return files;
+}
+/** Human-readable rendering of a dry-run plan. */
+export function formatUpdatePlan(plan) {
+    const lines = [];
+    if (plan.changes.length === 0) {
+        lines.push('No changes: skills and commands are up to date.');
+    }
+    else {
+        lines.push(`${plan.changes.length} file(s) would change:`);
+        const width = Math.max(...plan.changes.map((change) => change.action.length));
+        for (const change of plan.changes) {
+            lines.push(`  ${change.action.padEnd(width)}  ${change.path}  (${change.tool})`);
+        }
+    }
+    for (const note of plan.notes) {
+        lines.push('');
+        lines.push(`Note: ${note.message}`);
+    }
+    for (const failure of plan.failures) {
+        lines.push('');
+        lines.push(`Would fail: ${failure.tool} (${failure.error})`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=update-plan.js.map

package/dist/core/update.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Update Command
+ *
+ * Refreshes FreeSpec skills and commands for configured tools.
+ * Supports profile-aware updates, delivery changes, migration, and smart update detection.
+ */
+import { type FileView } from './file-view.js';
+import { type UpdatePlan } from './update-plan.js';
+/**
+ * Options for the update command.
+ */
+export interface UpdateCommandOptions {
+    /** Force update even when tools are up to date */
+    force?: boolean;
+    /**
+     * Record what the update would change and write nothing. Set by `plan()`;
+     * callers use that instead of passing this directly.
+     */
+    dryRun?: boolean;
+}
+/**
+ * Scans installed workflow artifacts (skills and managed commands) across all configured tools.
+ * Returns the union of detected workflow IDs that match ALL_WORKFLOWS.
+ *
+ * Wrapper around the shared migration module's scanInstalledWorkflows that accepts tool IDs.
+ */
+export declare function scanInstalledWorkflows(projectPath: string, toolIds: string[], view?: FileView): string[];
+export declare class UpdateCommand {
+    private readonly force;
+    private readonly dryRun;
+    private recorder;
+    private ops;
+    constructor(options?: UpdateCommandOptions);
+    /**
+     * Reports what `execute` would add, change or delete, writing nothing.
+     *
+     * Same code path as the real update: the plan is recorded by the write seam
+     * the generation loop already goes through, so it cannot drift from it.
+     */
+    plan(projectPath: string): Promise<UpdatePlan>;
+    /** Prints progress on a real run, stays quiet while planning. */
+    private log;
+    /** A spinner on a real run, a no-op while planning. */
+    private startSpinner;
+    /**
+     * Refreshes FreeSpec skills and commands for all configured tools,
+     * regenerating artifacts according to the effective profile and delivery mode.
+     *
+     * @param projectPath - Path to the project root containing the freespec directory
+     */
+    execute(projectPath: string): Promise<void>;
+    /**
+     * Records the shared-skills-root owner through the write seam, so a dry run
+     * lists the marker file a real update would write.
+     */
+    private writeSharedSkillTarget;
+    /**
+     * Where a real update throws for failed tools, it also stops. A dry run
+     * stops at the same point - so it plans nothing the real update would not
+     * reach - but returns instead of throwing: the failures are already in the
+     * plan, and the caller still gets every change planned before them.
+     *
+     * @returns whether the update stops here.
+     */
+    private stopIfUpdateFailed;
+    /** The tree as the real update would see it at this point. */
+    private get view();
+    /**
+     * Plans the moves out of former tool roots that a non-interactive update
+     * makes, against the tree as planned so far.
+     */
+    private planLegacyToolMoves;
+    /**
+     * Tools whose SKILL.md bodies no longer match what this CLI generates.
+     *
+     * Skill freshness was decided solely by the `generatedBy:` line, so a body
+     * edited after generation — a "helpful" PR touching `.claude/skills/**`, a
+     * dotfile sync, another agent — left `update` reporting the install healthy.
+     * Command files never had that gap: `areCommandFilesUpToDate` content-
+     * compares them, and the same comparison belongs on the higher-authority
+     * surface. A missing skill file is left to the profile-sync check, which
+     * already knows what a partial install means.
+     */
+    private findToolsWithDriftedSkills;
+    /**
+     * Display message when all tools are up to date.
+     */
+    private displayUpToDateMessage;
+    /**
+     * Display the update plan showing which tools need updating.
+     */
+    private displayUpdatePlan;
+    /**
+     * Shows manual setup notes for configured tools that need extra
+     * configuration before they pick up generated files.
+     */
+    private displaySetupNotes;
+    /**
+     * Detects new tool directories that aren't currently configured and displays a hint.
+     */
+    private detectNewTools;
+    /**
+     * Prints the profile notes, in order, with one pointer at
+     * `freespec config profile` rather than three.
+     *
+     * Every note is evaluated: reading them as one short-circuited `||` chain
+     * would swallow whichever ran second.
+     */
+    private displayProfileNotes;
+    /**
+     * Displays a note about extra workflows installed that aren't in the current profile.
+     */
+    private displayExtraWorkflowsNote;
+    /**
+     * Point out core workflows a custom profile is missing, so releases that
+     * grow CORE_WORKFLOWS stay discoverable. Keep custom profiles user-owned;
+     * do not mutate them.
+     */
+    private displayMissingCoreWorkflowsNote;
+    /**
+     * Removes skill directories for workflows when delivery changed to commands-only.
+     * Returns the number of directories removed.
+     */
+    private removeSkillDirs;
+    /**
+     * Removes skill directories for workflows that are no longer selected in the active profile.
+     * Returns the number of directories removed.
+     */
+    private removeUnselectedSkillDirs;
+    /**
+     * Removes command files for workflows when delivery changed to skills-only.
+     * Returns the number of files removed.
+     */
+    private removeCommandFiles;
+    /**
+     * Removes command files for workflows that are no longer selected in the active profile.
+     * Returns the number of files removed.
+     */
+    private removeUnselectedCommandFiles;
+    /**
+     * Offers to move FreeSpec content out of a renamed tool's former directory
+     * when the old location might still be the live one — today, Windsurf's
+     * `.windsurf/` after the Devin Desktop rebrand.
+     *
+     * Interactive runs are asked, because nothing on disk distinguishes a user
+     * who took the rebrand from one still on a pre-rebrand Windsurf build that
+     * reads only `.windsurf/`. `--force` and non-interactive runs migrate, which
+     * is what an unattended upgrade wants.
+     */
+    /** Surfaces files the move left behind rather than overwriting. */
+    private reportKeptInPlace;
+    private offerConsentedLegacyMigrations;
+}
+//# sourceMappingURL=update.d.ts.map