@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/shared/skill-paths.js

@@ -0,0 +1,23 @@
+import os from 'node:os';
+import path from 'node:path';
+import { AI_TOOLS } from '../config.js';
+export function toolSupportsSkills(tool) {
+    return Boolean(tool.skillsDir || tool.globalSkillsDir);
+}
+export function getSkillCapableTools() {
+    return AI_TOOLS.filter(toolSupportsSkills);
+}
+export function hasGlobalSkillTarget(tool) {
+    return Boolean(tool.globalSkillsDir);
+}
+export function resolveToolSkillsDir(projectRoot, tool, options = {}) {
+    if (tool.globalSkillsDir) {
+        const homeDir = options.homeDir ?? process.env.USERPROFILE ?? process.env.HOME ?? os.homedir();
+        return path.join(homeDir, tool.globalSkillsDir, 'skills');
+    }
+    if (tool.skillsDir) {
+        return path.join(projectRoot, tool.skillsDir, 'skills');
+    }
+    throw new Error(`Tool '${tool.value}' does not support skill generation.`);
+}
+//# sourceMappingURL=skill-paths.js.map

package/dist/core/shared/tool-detection.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Tool Detection Utilities
+ *
+ * Shared utilities for detecting tool configurations and version status.
+ */
+import { type Delivery } from '../global-config.js';
+import { type FileView } from '../file-view.js';
+/**
+ * Names of skill directories created by freespec init.
+ */
+export declare const SKILL_NAMES: readonly ["freespec-新建", "freespec-深思", "freespec-需求", "freespec-设计", "freespec-任务", "freespec-审文档", "freespec-用例", "freespec-验收", "freespec-写Java", "freespec-审Java"];
+export type SkillName = (typeof SKILL_NAMES)[number];
+/**
+ * IDs of command templates created by freespec init.
+ */
+export declare const COMMAND_IDS: readonly ["新建", "深思", "需求", "设计", "任务", "审文档", "用例", "验收", "写Java", "审Java"];
+export type CommandId = (typeof COMMAND_IDS)[number];
+/**
+ * Status of skill configuration for a tool.
+ */
+export interface ToolSkillStatus {
+    /** Whether the tool has any skills configured */
+    configured: boolean;
+    /** Whether all skills are configured */
+    fullyConfigured: boolean;
+    /** Number of skills currently configured */
+    skillCount: number;
+}
+/**
+ * Version information for a tool's skills.
+ */
+export interface ToolVersionStatus {
+    /** The tool ID */
+    toolId: string;
+    /** The tool's display name */
+    toolName: string;
+    /** Whether the tool has any skills or commands configured */
+    configured: boolean;
+    /**
+     * The generatedBy version recorded in the tool's skill files. For a tool that
+     * has commands but no skills, the current version when the command files match
+     * what would be generated now. Null when neither says the files are current.
+     */
+    generatedByVersion: string | null;
+    /** Whether the tool needs updating (version mismatch or missing) */
+    needsUpdate: boolean;
+}
+/**
+ * Gets the list of tools with skillsDir configured.
+ */
+export declare function getToolsWithSkillsDir(): string[];
+/**
+ * Checks which skill files exist for a tool.
+ */
+export declare function getToolSkillStatus(projectRoot: string, toolId: string, view?: FileView): ToolSkillStatus;
+/**
+ * Checks whether a tool has at least one generated FreeSpec command file.
+ */
+export declare function toolHasAnyConfiguredCommand(projectPath: string, toolId: string, view?: FileView): boolean;
+/**
+ * Checks whether command files for a tool on disk match current generated command contents.
+ *
+ * Command files carry no version stamp, so content equality is the only available
+ * "is this current?" signal for a commands-only install.
+ */
+export declare function areCommandFilesUpToDate(projectRoot: string, toolId: string, options?: {
+    workflows?: readonly string[];
+    /** The tree to read; the disk unless an update is planning. */
+    view?: FileView;
+}): boolean;
+/**
+ * Gets the skill status for all tools with skillsDir configured.
+ */
+export declare function getToolStates(projectRoot: string): Map<string, ToolSkillStatus>;
+/**
+ * Extracts the generatedBy version from a skill file's YAML frontmatter.
+ * Returns null if the field is not found or the file doesn't exist.
+ */
+export declare function extractGeneratedByVersion(skillFilePath: string, view?: FileView): string | null;
+/**
+ * Gets version status for a tool by reading its skill files, falling back to a
+ * command-content fingerprint for installs that have commands but no skills.
+ */
+export declare function getToolVersionStatus(projectRoot: string, toolId: string, currentVersion: string, options?: {
+    workflows?: readonly string[];
+    /** The tree to read; the disk unless an update is planning. */
+    view?: FileView;
+    /** Effective delivery; read from the global config when omitted. */
+    delivery?: Delivery;
+}): ToolVersionStatus;
+/**
+ * Gets all configured tools in the project (configured via skills or commands).
+ */
+export declare function getConfiguredTools(projectRoot: string, view?: FileView): string[];
+/**
+ * Gets version status for all configured tools.
+ */
+export declare function getAllToolVersionStatus(projectRoot: string, currentVersion: string): ToolVersionStatus[];
+//# sourceMappingURL=tool-detection.d.ts.map

package/dist/core/shared/tool-detection.js

@@ -0,0 +1,318 @@
+/**
+ * Tool Detection Utilities
+ *
+ * Shared utilities for detecting tool configurations and version status.
+ */
+import path from 'path';
+import { AI_TOOLS, OPENSPEC_SKILL_NAMES } from '../config.js';
+import { CommandAdapterRegistry, generateCommands } from '../command-generation/index.js';
+import { getCommandContents } from './skill-generation.js';
+import { getGlobalConfig } from '../global-config.js';
+import { getProfileWorkflows, ALL_WORKFLOWS } from '../profiles.js';
+import { isSharedSkillTargetActive, hasLegacySkills, readSharedSkillTarget, reconcileSharedSkillTargets, } from '../shared-skill-target.js';
+import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, resolveCommandSurfaceCapability, } from '../command-surface.js';
+import { getSkillCapableTools, resolveToolSkillsDir, toolSupportsSkills, } from './skill-paths.js';
+import { DISK_VIEW } from '../file-view.js';
+/**
+ * Names of skill directories created by freespec init.
+ */
+export const SKILL_NAMES = OPENSPEC_SKILL_NAMES;
+/**
+ * IDs of command templates created by freespec init.
+ */
+export const COMMAND_IDS = ALL_WORKFLOWS;
+/**
+ * Gets the list of tools with skillsDir configured.
+ */
+export function getToolsWithSkillsDir() {
+    return getSkillCapableTools().map((tool) => tool.value);
+}
+/**
+ * Checks which skill files exist for a tool.
+ */
+export function getToolSkillStatus(projectRoot, toolId, view = DISK_VIEW) {
+    const tool = AI_TOOLS.find((t) => t.value === toolId);
+    if (!tool || !toolSupportsSkills(tool)) {
+        return { configured: false, fullyConfigured: false, skillCount: 0 };
+    }
+    if (tool.skillsDir && !isSharedSkillTargetActive(projectRoot, toolId, view)) {
+        return { configured: false, fullyConfigured: false, skillCount: 0 };
+    }
+    const skillsDirs = [
+        resolveToolSkillsDir(projectRoot, tool),
+        ...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectRoot, root, 'skills')),
+    ];
+    let skillCount = 0;
+    for (const skillName of SKILL_NAMES) {
+        if (skillsDirs.some((skillsDir) => view.exists(path.join(skillsDir, skillName, 'SKILL.md')))) {
+            skillCount++;
+        }
+    }
+    return {
+        configured: skillCount > 0,
+        fullyConfigured: skillCount === SKILL_NAMES.length,
+        skillCount,
+    };
+}
+/**
+ * Checks whether a tool has at least one generated FreeSpec command file.
+ */
+export function toolHasAnyConfiguredCommand(projectPath, toolId, view = DISK_VIEW) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    if (!adapter)
+        return false;
+    for (const commandId of COMMAND_IDS) {
+        const cmdPath = adapter.getFilePath(commandId);
+        const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+        if (view.exists(fullPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Normalizes checkout artifacts that are not real content drift: a UTF-8 BOM and
+ * CRLF line endings, which a Windows clone with `core.autocrlf` reintroduces on
+ * every checkout of committed command files.
+ */
+function normalizeCommandContent(content) {
+    return content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+}
+/**
+ * Checks whether command files for a tool on disk match current generated command contents.
+ *
+ * Command files carry no version stamp, so content equality is the only available
+ * "is this current?" signal for a commands-only install.
+ */
+export function areCommandFilesUpToDate(projectRoot, toolId, options) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    if (!adapter)
+        return false;
+    const view = options?.view ?? DISK_VIEW;
+    let workflows;
+    if (options?.workflows) {
+        workflows = options.workflows;
+    }
+    else {
+        try {
+            const globalCfg = getGlobalConfig();
+            const profile = globalCfg.profile ?? 'core';
+            workflows = getProfileWorkflows(profile, globalCfg.workflows);
+        }
+        catch {
+            workflows = ALL_WORKFLOWS;
+        }
+    }
+    const knownWorkflows = workflows.filter((w) => ALL_WORKFLOWS.includes(w));
+    const commandContents = getCommandContents(knownWorkflows);
+    const generatedCommands = generateCommands(commandContents, adapter);
+    if (generatedCommands.length === 0) {
+        return false;
+    }
+    for (const cmd of generatedCommands) {
+        const cmdPath = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectRoot, cmd.path);
+        if (!view.exists(cmdPath)) {
+            return false;
+        }
+        try {
+            const existingContent = view.read(cmdPath);
+            if (normalizeCommandContent(existingContent) !== normalizeCommandContent(cmd.fileContent)) {
+                return false;
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    // Also check no extra command files exist for deselected workflows
+    const desiredWorkflowSet = new Set(knownWorkflows);
+    for (const workflow of ALL_WORKFLOWS) {
+        if (desiredWorkflowSet.has(workflow))
+            continue;
+        const cmdPath = adapter.getFilePath(workflow);
+        const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectRoot, cmdPath);
+        if (view.exists(fullPath)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Gets the skill status for all tools with skillsDir configured.
+ */
+export function getToolStates(projectRoot) {
+    const states = new Map();
+    const tools = getSkillCapableTools();
+    for (const tool of tools) {
+        const skillStatus = getToolSkillStatus(projectRoot, tool.value);
+        const markerConfigured = Boolean(tool.skillsDir) &&
+            readSharedSkillTarget(projectRoot, tool.skillsDir) === tool.value;
+        states.set(tool.value, markerConfigured
+            ? { ...skillStatus, configured: true }
+            : skillStatus);
+    }
+    const configuredTools = tools.filter((tool) => tool.skillsDir && states.get(tool.value)?.configured);
+    const activeSharedTargets = new Set(reconcileSharedSkillTargets(projectRoot, configuredTools).map((tool) => tool.value));
+    for (const tool of configuredTools) {
+        if (!activeSharedTargets.has(tool.value)) {
+            states.set(tool.value, { configured: false, fullyConfigured: false, skillCount: 0 });
+        }
+    }
+    return states;
+}
+/**
+ * Extracts the generatedBy version from a skill file's YAML frontmatter.
+ * Returns null if the field is not found or the file doesn't exist.
+ */
+export function extractGeneratedByVersion(skillFilePath, view = DISK_VIEW) {
+    try {
+        if (!view.exists(skillFilePath)) {
+            return null;
+        }
+        const content = view.read(skillFilePath);
+        // Look for generatedBy in the YAML frontmatter
+        // The file format is:
+        // ---
+        // ...
+        // metadata:
+        //   author: freespec
+        //   version: "1.0"
+        //   generatedBy: "0.23.0"
+        // ---
+        // Scanned per line, and with `[ \t]` rather than `\s`, so the leading
+        // whitespace run can never cross a newline. A single `m`-anchored `\s*`
+        // over the whole file re-scans it from every line start, which is
+        // quadratic on a whitespace-heavy SKILL.md.
+        for (const line of content.split(/\r\n?|\n/)) {
+            const generatedByMatch = line.match(/^[ \t]*generatedBy:[ \t]*["']?([^"'\n]+)["']?[ \t]*$/);
+            if (generatedByMatch && generatedByMatch[1]) {
+                return generatedByMatch[1].trim();
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets version status for a tool by reading its skill files, falling back to a
+ * command-content fingerprint for installs that have commands but no skills.
+ */
+export function getToolVersionStatus(projectRoot, toolId, currentVersion, options) {
+    const view = options?.view ?? DISK_VIEW;
+    const tool = AI_TOOLS.find((t) => t.value === toolId);
+    if (!tool || !toolSupportsSkills(tool)) {
+        return {
+            toolId,
+            toolName: toolId,
+            configured: false,
+            generatedByVersion: null,
+            needsUpdate: false,
+        };
+    }
+    const skillsDirs = [
+        resolveToolSkillsDir(projectRoot, tool),
+        ...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectRoot, root, 'skills')),
+    ];
+    let generatedByVersion = null;
+    let foundSkill = false;
+    // 1. Find the first skill file that exists and read its version
+    for (const skillName of SKILL_NAMES) {
+        for (const skillsDir of skillsDirs) {
+            const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
+            if (view.exists(skillFile)) {
+                generatedByVersion = extractGeneratedByVersion(skillFile, view);
+                foundSkill = true;
+                break;
+            }
+        }
+        if (foundSkill)
+            break;
+    }
+    const skillConfigured = getToolSkillStatus(projectRoot, toolId, view).configured;
+    const commandConfigured = toolHasAnyConfiguredCommand(projectRoot, toolId, view);
+    const markerConfigured = Boolean(tool.skillsDir) &&
+        readSharedSkillTarget(projectRoot, tool.skillsDir, view) === toolId;
+    const configured = skillConfigured || commandConfigured || markerConfigured;
+    // 2. Commands-only installs have no skill file to read a version from, so fall
+    //    back to comparing the generated command content. Deliberately skipped when
+    //    skill files exist: an unreadable version there must still force a rewrite.
+    if (!skillConfigured && commandConfigured && areCommandFilesUpToDate(projectRoot, toolId, options)) {
+        generatedByVersion = currentVersion;
+    }
+    if (!skillConfigured && !commandConfigured && markerConfigured) {
+        const delivery = options?.delivery ?? getGlobalConfig().delivery ?? 'both';
+        if (!shouldGenerateSkillsForTool(toolId, delivery) &&
+            !shouldGenerateCommandsForTool(toolId, delivery)) {
+            generatedByVersion = currentVersion;
+        }
+    }
+    // 3. A version marker in a skill file only proves the SKILL files came from
+    //    this CLI. It says nothing about the command files written beside them,
+    //    which a user may have hand-edited or a partial write may have truncated.
+    //    Without this, `update` answered "all tools up to date" while a damaged
+    //    command file sat on disk, repairable only by knowing to pass --force.
+    //    The content comparison already exists; it was simply never consulted
+    //    once a skill file supplied a version.
+    //
+    //    Scoped to tools that have BOTH, so the commands-only path above keeps
+    //    its exact behaviour, and skipped when the delivery mode generates no
+    //    commands for this tool - there would be nothing to compare against, and
+    //    `areCommandFilesUpToDate` reports an empty command set as "not current".
+    let commandsDrifted = false;
+    if (skillConfigured && commandConfigured) {
+        let generatesCommands = true;
+        try {
+            generatesCommands = shouldGenerateCommandsForTool(toolId, options?.delivery ?? getGlobalConfig().delivery ?? 'both');
+        }
+        catch {
+            generatesCommands = true;
+        }
+        commandsDrifted =
+            generatesCommands && !areCommandFilesUpToDate(projectRoot, toolId, options);
+    }
+    const needsUpdate = configured &&
+        (generatedByVersion === null ||
+            generatedByVersion !== currentVersion ||
+            commandsDrifted);
+    return {
+        toolId,
+        toolName: tool.name,
+        configured,
+        generatedByVersion,
+        needsUpdate,
+    };
+}
+/**
+ * Gets all configured tools in the project (configured via skills or commands).
+ */
+export function getConfiguredTools(projectRoot, view = DISK_VIEW) {
+    const configured = AI_TOOLS
+        .filter((t) => {
+        if (!toolSupportsSkills(t))
+            return false;
+        return (getToolSkillStatus(projectRoot, t.value, view).configured ||
+            toolHasAnyConfiguredCommand(projectRoot, t.value, view) ||
+            (resolveCommandSurfaceCapability(t.value) === 'adapter-backed' &&
+                hasLegacySkills(projectRoot, t, view)) ||
+            (Boolean(t.skillsDir) &&
+                readSharedSkillTarget(projectRoot, t.skillsDir, view) === t.value));
+    });
+    const activeProjectTools = new Set(reconcileSharedSkillTargets(projectRoot, configured.filter((tool) => tool.skillsDir), view).map((tool) => tool.value));
+    return configured
+        .filter((tool) => tool.globalSkillsDir ||
+        toolHasAnyConfiguredCommand(projectRoot, tool.value, view) ||
+        (resolveCommandSurfaceCapability(tool.value) === 'adapter-backed' &&
+            hasLegacySkills(projectRoot, tool, view)) ||
+        activeProjectTools.has(tool.value))
+        .map((tool) => tool.value);
+}
+/**
+ * Gets version status for all configured tools.
+ */
+export function getAllToolVersionStatus(projectRoot, currentVersion) {
+    const configuredTools = getConfiguredTools(projectRoot);
+    return configuredTools.map((toolId) => getToolVersionStatus(projectRoot, toolId, currentVersion));
+}
+//# sourceMappingURL=tool-detection.js.map

package/dist/core/shared-skill-target.d.ts

@@ -0,0 +1,51 @@
+import { type AIToolOption } from './config.js';
+import { type FileView } from './file-view.js';
+/** Reads a valid-looking marker value without letting linked roots escape. */
+export declare function readSharedSkillTarget(projectPath: string, skillsDir: string, view?: FileView): string | undefined;
+/** Whether a tool still has an allowlisted managed skill under an old root. */
+export declare function hasLegacySkills(projectPath: string, tool: AIToolOption, view?: FileView): boolean;
+/**
+ * Chooses the one selected tool that may render each physical skills root.
+ * Command files are not part of this arbitration: tools that share a skills
+ * root can still write their own command surface elsewhere under that root.
+ *
+ * Existing compatible owners win. On a new root, prefer a skills-native
+ * renderer over an adapter-backed renderer because its references remain
+ * usable by every consumer of the shared tree. Codex is the best fresh owner
+ * because its renderer includes both Codex and generic skill invocation forms.
+ */
+export declare function resolveSharedSkillWriters(projectPath: string, tools: AIToolOption[], view?: FileView): Set<string>;
+/**
+ * A shared skill root can only hold one rendered variant of each skill.
+ * Keep the writer recorded so later updates do not infer every tool that
+ * happens to use the same directory.
+ */
+export declare function reconcileSharedSkillTargets(projectPath: string, tools: AIToolOption[], view?: FileView): AIToolOption[];
+/**
+ * Returns whether a tool is the active writer for its physical skills root.
+ * Non-shared roots are always active.
+ */
+export declare function isSharedSkillTargetActive(projectPath: string, toolId: string, view?: FileView): boolean;
+/**
+ * The tool that already owns `toolId`'s shared skills root, when a DIFFERENT
+ * one does. Returns the owner's tool id only when the root already carries an
+ * ownership signal (a marker or generated skills) AND reconciliation resolves
+ * it to another tool. An empty or unclaimed root returns undefined, so a
+ * genuine first-time legacy upgrade — e.g. a Codex-only user with no `.agents`
+ * yet — is never reported as owned.
+ */
+export declare function sharedSkillRootOwner(projectPath: string, toolId: string): string | undefined;
+/**
+ * Whether generating `toolId` into its shared skills root would clobber a tree
+ * a DIFFERENT tool already owns — the guard the legacy-upgrade path uses before
+ * writing skills. See {@link sharedSkillRootOwner} for the ownership rules.
+ */
+export declare function sharedSkillRootOwnedByOther(projectPath: string, toolId: string): boolean;
+/**
+ * Path of the owner marker for a tool's shared skills root, or null when the
+ * tool has no shared root to mark. Lets a caller write the marker itself —
+ * `update` routes it through its write seam so a dry run can list it.
+ */
+export declare function sharedSkillTargetMarkerPath(projectPath: string, toolId: string): string | null;
+export declare function writeSharedSkillTarget(projectPath: string, toolId: string): void;
+//# sourceMappingURL=shared-skill-target.d.ts.map