@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/references.js

@@ -0,0 +1,46 @@
+/**
+ * Strings rendered into agent guidance. One line in, one line out: control
+ * characters and newlines must never let hostile content forge instruction lines.
+ */
+export function sanitizeInline(value, maxLength = 300) {
+    const flattened = value
+        .replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u206f]+/g, ' ')
+        .trim();
+    return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}…` : flattened;
+}
+/**
+ * The tags the instruction printer uses to frame its blocks. A block ends at
+ * its own closing tag and nowhere else, so this is the entire breakout
+ * surface: neutralize these and repo-supplied text cannot escape the element
+ * that marks it as data.
+ */
+const ENVELOPE_TAGS = [
+    'artifact',
+    'dependencies',
+    'dependency',
+    'description',
+    'instruction',
+    'output',
+    'path',
+    'project_context',
+    'rules',
+    'success_criteria',
+    'task',
+    'template',
+    'unlocks',
+    'warning',
+];
+const ENVELOPE_TAG = new RegExp(`<(/?)(${ENVELOPE_TAGS.join('|')})(\\s[^<>]*)?>`, 'gi');
+/** Neutralize the envelope's own tags in repo-supplied text. */
+export function escapeEnvelopeTags(value) {
+    return value.replace(ENVELOPE_TAG, (_match, slash, tag, attrs) => `&lt;${slash}${tag}${attrs ?? ''}&gt;`);
+}
+/** Escape attribute metacharacters so a quote cannot close the attribute. */
+export function escapeEnvelopeAttribute(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+//# sourceMappingURL=references.js.map

package/dist/core/root-selection.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Resolves the local FreeSpec root for the supported commands.
+ *
+ * A root is the nearest ancestor whose `freespec/` directory is a planning
+ * directory (it contains a `<名称>变更` folder) or holds `config.yaml`.
+ * With neither, commands may treat the current directory as an implicit root.
+ */
+import { type PlanningHome } from './planning-home.js';
+export type FreeSpecRootSource = 'nearest' | 'implicit';
+export interface StoreSelectorOptions {
+    store?: string;
+    storePath?: string;
+}
+export interface ResolveFreeSpecRootOptions extends StoreSelectorOptions {
+    startPath?: string;
+    allowImplicitRoot?: boolean;
+    globalDataDir?: string;
+}
+export interface ResolvedFreeSpecRoot {
+    path: string;
+    changesDir: string;
+    specsDir: string;
+    defaultSchema: string;
+    source: FreeSpecRootSource;
+}
+export interface RootSelectionDiagnostic {
+    severity: 'error';
+    code: string;
+    message: string;
+    target?: string;
+    fix?: string;
+}
+export declare class RootSelectionError extends Error {
+    readonly diagnostic: RootSelectionDiagnostic;
+    constructor(message: string, code: string, options?: {
+        target?: string;
+        fix?: string;
+    });
+}
+export declare function isRootSelectionError(error: unknown): error is RootSelectionError;
+export declare function resolveFreeSpecRoot(options?: ResolveFreeSpecRootOptions): Promise<ResolvedFreeSpecRoot>;
+export interface RootOutput {
+    path: string;
+    source: FreeSpecRootSource;
+}
+export declare function toRootOutput(root: ResolvedFreeSpecRoot): RootOutput;
+export declare function toPlanningHome(root: ResolvedFreeSpecRoot): PlanningHome;
+/**
+ * CLI adapter shared by the supported commands. In JSON mode a resolution
+ * failure is reported as a machine-readable payload on stdout with a
+ * non-zero exit code; the caller must return when this resolves to null.
+ */
+export declare function resolveRootForCommand(selector: StoreSelectorOptions, output?: {
+    json?: boolean;
+    failurePayload?: Record<string, unknown>;
+    /** Commands that require an existing root set this to false. */
+    allowImplicitRoot?: boolean;
+}): Promise<ResolvedFreeSpecRoot | null>;
+//# sourceMappingURL=root-selection.d.ts.map

package/dist/core/root-selection.js

@@ -0,0 +1,132 @@
+/**
+ * Resolves the local FreeSpec root for the supported commands.
+ *
+ * A root is the nearest ancestor whose `freespec/` directory is a planning
+ * directory (it contains a `<名称>变更` folder) or holds `config.yaml`.
+ * With neither, commands may treat the current directory as an implicit root.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { changeParentDir, DEFAULT_SCHEMA } from './change-layout.js';
+import { findRepoPlanningRootSync } from './planning-home.js';
+import { classifyFreeSpecDir } from './project-config.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+export class RootSelectionError extends Error {
+    diagnostic;
+    constructor(message, code, options = {}) {
+        super(message);
+        this.name = 'RootSelectionError';
+        this.diagnostic = {
+            severity: 'error',
+            code,
+            message,
+            ...options,
+        };
+    }
+}
+export function isRootSelectionError(error) {
+    return error instanceof RootSelectionError;
+}
+function makeRoot(rootPath, source) {
+    return {
+        path: rootPath,
+        changesDir: changeParentDir(rootPath),
+        specsDir: path.join(rootPath, 'freespec', 'specs'),
+        defaultSchema: DEFAULT_SCHEMA,
+        source,
+    };
+}
+function canonicalDirectory(startPath) {
+    const resolved = path.resolve(startPath);
+    try {
+        const stats = fs.statSync(resolved);
+        const dir = stats.isDirectory() ? resolved : path.dirname(resolved);
+        return FileSystemUtils.canonicalizeExistingPath(dir);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * An `freespec/` directory is a root when it holds a change folder or a
+ * config file. A bare directory is not enough: `~/freespec` would otherwise
+ * capture every command under the home tree.
+ */
+function findQualifyingRootSync(startPath) {
+    let candidate = findRepoPlanningRootSync(startPath);
+    while (candidate) {
+        const { hasPlanningShape, pointer } = classifyFreeSpecDir(candidate);
+        if (hasPlanningShape || pointer.filePath) {
+            return candidate;
+        }
+        const parent = path.dirname(candidate);
+        if (parent === candidate) {
+            return null;
+        }
+        candidate = findRepoPlanningRootSync(parent);
+    }
+    return null;
+}
+function rejectStoreSelection() {
+    throw new RootSelectionError('This FreeSpec build uses the local freespec/ directory. Store selection is not available.', 'store_not_supported', {
+        target: 'freespec.root',
+        fix: 'Run freespec init in the project, then rerun the command there.',
+    });
+}
+export async function resolveFreeSpecRoot(options = {}) {
+    if (options.storePath !== undefined || options.store !== undefined) {
+        rejectStoreSelection();
+    }
+    const startPath = options.startPath ?? process.cwd();
+    const nearestRoot = findQualifyingRootSync(startPath);
+    if (nearestRoot) {
+        const { pointer } = classifyFreeSpecDir(nearestRoot);
+        if (pointer.value !== undefined && pointer.filePath) {
+            console.error(`Warning: ${pointer.filePath} declares store '${pointer.value}'. This build uses the local freespec/ directory and ignores that declaration.`);
+        }
+        return makeRoot(nearestRoot, 'nearest');
+    }
+    if (options.allowImplicitRoot === false) {
+        throw new RootSelectionError('No FreeSpec root found from the current directory.', 'no_freespec_root', { target: 'freespec.root', fix: 'Run freespec init to create a root here.' });
+    }
+    return makeRoot(canonicalDirectory(startPath), 'implicit');
+}
+export function toRootOutput(root) {
+    return {
+        path: root.path,
+        source: root.source,
+    };
+}
+export function toPlanningHome(root) {
+    return {
+        kind: 'repo',
+        root: root.path,
+        changesDir: root.changesDir,
+        defaultSchema: root.defaultSchema,
+    };
+}
+/**
+ * CLI adapter shared by the supported commands. In JSON mode a resolution
+ * failure is reported as a machine-readable payload on stdout with a
+ * non-zero exit code; the caller must return when this resolves to null.
+ */
+export async function resolveRootForCommand(selector, output = {}) {
+    try {
+        return await resolveFreeSpecRoot({
+            ...(selector.store !== undefined ? { store: selector.store } : {}),
+            ...(selector.storePath !== undefined ? { storePath: selector.storePath } : {}),
+            ...(output.allowImplicitRoot !== undefined
+                ? { allowImplicitRoot: output.allowImplicitRoot }
+                : {}),
+        });
+    }
+    catch (error) {
+        if (output.json && isRootSelectionError(error)) {
+            console.log(JSON.stringify({ ...(output.failurePayload ?? {}), status: [error.diagnostic] }, null, 2));
+            process.exitCode = 1;
+            return null;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=root-selection.js.map

package/dist/core/shared/allowed-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-approved tools for generated skills and slash commands, emitted as the
+ * `allowed-tools` frontmatter field (Agent Skills standard for SKILL.md;
+ * same field for Claude Code slash commands). Scoped to the FreeSpec CLI so
+ * agents that honor it stop prompting on each `freespec` call; the field
+ * only pre-approves — it does not restrict — so any other tool a skill or
+ * command needs (Read, Write, arbitrary Bash for builds/tests) stays
+ * available under the user's normal permission settings. Tools that don't
+ * recognize the field ignore it.
+ */
+export declare const OPENSPEC_CLI_ALLOWED_TOOLS = "Bash(freespec:*)";
+//# sourceMappingURL=allowed-tools.d.ts.map

package/dist/core/shared/allowed-tools.js

@@ -0,0 +1,12 @@
+/**
+ * Pre-approved tools for generated skills and slash commands, emitted as the
+ * `allowed-tools` frontmatter field (Agent Skills standard for SKILL.md;
+ * same field for Claude Code slash commands). Scoped to the FreeSpec CLI so
+ * agents that honor it stop prompting on each `freespec` call; the field
+ * only pre-approves — it does not restrict — so any other tool a skill or
+ * command needs (Read, Write, arbitrary Bash for builds/tests) stays
+ * available under the user's normal permission settings. Tools that don't
+ * recognize the field ignore it.
+ */
+export const OPENSPEC_CLI_ALLOWED_TOOLS = 'Bash(freespec:*)';
+//# sourceMappingURL=allowed-tools.js.map

package/dist/core/shared/ide-restart.d.ts

@@ -0,0 +1,26 @@
+/**
+ * IDE restart hint
+ *
+ * Shared restart guidance for tools successfully configured by init or update.
+ * The wording covers additions, updates, and removals, including an empty
+ * workflow selection that removes every generated file.
+ */
+import type { Delivery } from '../global-config.js';
+/** The surface a restart hint names. Absent when no hint is due. */
+export type IdeRestartSurface = 'commands' | 'skills';
+/**
+ * Both conditions stay coupled to the SAME tool: its surfaces are loaded by a
+ * long-running editor process (a CLI picks them up immediately, so a restart
+ * line would be wrong for it — see #1067), and it supports a generated surface
+ * under the active delivery. A CLI tool's commands must not determine the hint
+ * for an IDE tool that only supports skills. Commands take precedence when
+ * both surfaces are supported under the active delivery.
+ */
+export declare function resolveIdeRestartSurface(toolIds: readonly string[], delivery: Delivery): IdeRestartSurface | null;
+/**
+ * The restart line to print, or null when no restart is needed. Deliberately
+ * not "slash commands": Amazon Q's generated files are prompt-library entries
+ * invoked with `@`, so promising slash commands would be wrong for it.
+ */
+export declare function formatIdeRestart(toolIds: readonly string[], delivery: Delivery): string | null;
+//# sourceMappingURL=ide-restart.d.ts.map

package/dist/core/shared/ide-restart.js

@@ -0,0 +1,42 @@
+/**
+ * IDE restart hint
+ *
+ * Shared restart guidance for tools successfully configured by init or update.
+ * The wording covers additions, updates, and removals, including an empty
+ * workflow selection that removes every generated file.
+ */
+import { AI_TOOLS } from '../config.js';
+import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, } from '../command-surface.js';
+function isIdeResident(toolId) {
+    return Boolean(AI_TOOLS.find((tool) => tool.value === toolId)?.requiresIdeRestart);
+}
+/**
+ * Both conditions stay coupled to the SAME tool: its surfaces are loaded by a
+ * long-running editor process (a CLI picks them up immediately, so a restart
+ * line would be wrong for it — see #1067), and it supports a generated surface
+ * under the active delivery. A CLI tool's commands must not determine the hint
+ * for an IDE tool that only supports skills. Commands take precedence when
+ * both surfaces are supported under the active delivery.
+ */
+export function resolveIdeRestartSurface(toolIds, delivery) {
+    const ideTools = [...new Set(toolIds)].filter(isIdeResident);
+    if (ideTools.some((toolId) => shouldGenerateCommandsForTool(toolId, delivery))) {
+        return 'commands';
+    }
+    if (ideTools.some((toolId) => shouldGenerateSkillsForTool(toolId, delivery))) {
+        return 'skills';
+    }
+    return null;
+}
+/**
+ * The restart line to print, or null when no restart is needed. Deliberately
+ * not "slash commands": Amazon Q's generated files are prompt-library entries
+ * invoked with `@`, so promising slash commands would be wrong for it.
+ */
+export function formatIdeRestart(toolIds, delivery) {
+    const surface = resolveIdeRestartSurface(toolIds, delivery);
+    return surface
+        ? `Restart your IDE to refresh ${surface}.`
+        : null;
+}
+//# sourceMappingURL=ide-restart.js.map

package/dist/core/shared/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared Utilities
+ *
+ * Common code shared between init and update commands.
+ */
+export { SKILL_NAMES, type SkillName, COMMAND_IDS, type CommandId, type ToolSkillStatus, type ToolVersionStatus, getToolsWithSkillsDir, getToolSkillStatus, getToolStates, extractGeneratedByVersion, getToolVersionStatus, getConfiguredTools, getAllToolVersionStatus, } from './tool-detection.js';
+export { type SkillTemplateEntry, type CommandTemplateEntry, getSkillTemplates, getCommandTemplates, getCommandContents, generateSkillContent, } from './skill-generation.js';
+export { copySkillExtras, getSkillFilesRoot } from './skill-files.js';
+export { type SkillCapableTool, toolSupportsSkills, getSkillCapableTools, hasGlobalSkillTarget, resolveToolSkillsDir, } from './skill-paths.js';
+export { type IdeRestartSurface, resolveIdeRestartSurface, formatIdeRestart, } from './ide-restart.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/shared/index.js

@@ -0,0 +1,11 @@
+/**
+ * Shared Utilities
+ *
+ * Common code shared between init and update commands.
+ */
+export { SKILL_NAMES, COMMAND_IDS, getToolsWithSkillsDir, getToolSkillStatus, getToolStates, extractGeneratedByVersion, getToolVersionStatus, getConfiguredTools, getAllToolVersionStatus, } from './tool-detection.js';
+export { getSkillTemplates, getCommandTemplates, getCommandContents, generateSkillContent, } from './skill-generation.js';
+export { copySkillExtras, getSkillFilesRoot } from './skill-files.js';
+export { toolSupportsSkills, getSkillCapableTools, hasGlobalSkillTarget, resolveToolSkillsDir, } from './skill-paths.js';
+export { resolveIdeRestartSurface, formatIdeRestart, } from './ide-restart.js';
+//# sourceMappingURL=index.js.map

package/dist/core/shared/skill-content-equivalence.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns whether a legacy Codex skill differs from the current canonical
+ * replacement only by generated version, checkout line endings/BOM, or the
+ * known Codex/generic dual-reference expansion.
+ */
+export declare function isLegacyCodexSkillEquivalentToCurrent(legacyContent: string, currentContent: string): boolean;
+//# sourceMappingURL=skill-content-equivalence.d.ts.map

package/dist/core/shared/skill-content-equivalence.js

@@ -0,0 +1,45 @@
+import { OPENSPEC_SKILL_NAMES } from '../config.js';
+const GENERATED_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const OPENSPEC_SKILL_NAME_SET = new Set(OPENSPEC_SKILL_NAMES);
+/**
+ * Normalizes checkout line endings and a valid generated version inside the
+ * YAML frontmatter. Free-form `generatedBy` text in the instructions remains
+ * material.
+ */
+function normalizeGeneratedSkill(content) {
+    const normalized = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const frontmatter = normalized.match(/^---\n[\s\S]*?\n---(?:\n|$)/)?.[0];
+    if (!frontmatter)
+        return normalized;
+    // `[ \t]` rather than `\s` so a leading/trailing whitespace run can never
+    // cross a newline: an `m`-anchored `\s*` re-scans from every line start,
+    // which is quadratic on a whitespace-heavy frontmatter. YAML indentation is
+    // spaces and tabs only, so matching is unchanged.
+    const versionLine = /^([ \t]*generatedBy:[ \t]*)(?:"([^"\n]+)"|'([^'\n]+)'|([^\s"'#]+))[ \t]*$/m;
+    const normalizedFrontmatter = frontmatter.replace(versionLine, (line, prefix, doubleQuoted, singleQuoted, bare) => {
+        const version = doubleQuoted ?? singleQuoted ?? bare;
+        return version && GENERATED_VERSION.test(version)
+            ? `${prefix}"<generated-version>"`
+            : line;
+    });
+    return normalizedFrontmatter + normalized.slice(frontmatter.length);
+}
+/**
+ * Converts only known generated dual references in current Codex content back
+ * to the direct syntax used by legacy `.codex` output.
+ */
+function toLegacyCodexReferences(content) {
+    return content.replace(/\$(freespec-[a-z0-9-]+) \(Codex\) or \/\1 \(other agents\)/g, (match, skillName) => OPENSPEC_SKILL_NAME_SET.has(skillName) ? `$${skillName}` : match);
+}
+/**
+ * Returns whether a legacy Codex skill differs from the current canonical
+ * replacement only by generated version, checkout line endings/BOM, or the
+ * known Codex/generic dual-reference expansion.
+ */
+export function isLegacyCodexSkillEquivalentToCurrent(legacyContent, currentContent) {
+    const normalizedLegacy = normalizeGeneratedSkill(legacyContent);
+    const normalizedCurrent = normalizeGeneratedSkill(currentContent);
+    return (normalizedLegacy === normalizedCurrent ||
+        normalizedLegacy === toLegacyCodexReferences(normalizedCurrent));
+}
+//# sourceMappingURL=skill-content-equivalence.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Package-root folder of skill extras. From dist/core/shared this is
+ * <package>/skill-files. Init and update copy it next to each SKILL.md.
+ */
+export declare function getSkillFilesRoot(): string;
+export declare function copySkillExtras(skillDir: string, workflowId: string): Promise<void>;
+//# sourceMappingURL=skill-files.d.ts.map

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

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const EXTRA_DIRS = ['references', 'config', 'scripts'];
+/**
+ * Package-root folder of skill extras. From dist/core/shared this is
+ * <package>/skill-files. Init and update copy it next to each SKILL.md.
+ */
+export function getSkillFilesRoot() {
+    const currentFile = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(currentFile), '..', '..', '..', 'skill-files');
+}
+async function copyTree(source, target) {
+    await fs.promises.mkdir(target, { recursive: true });
+    const entries = await fs.promises.readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const from = path.join(source, entry.name);
+        const to = path.join(target, entry.name);
+        if (entry.isDirectory()) {
+            await copyTree(from, to);
+        }
+        else if (entry.isFile()) {
+            await fs.promises.copyFile(from, to);
+        }
+    }
+}
+export async function copySkillExtras(skillDir, workflowId) {
+    if (!/^[\u4e00-\u9fffA-Za-z0-9]+$/u.test(workflowId)) {
+        throw new Error(`Refusing to copy skill files for ${workflowId}`);
+    }
+    const sourceRoot = path.join(getSkillFilesRoot(), workflowId);
+    if (!fs.existsSync(sourceRoot))
+        return;
+    for (const name of EXTRA_DIRS) {
+        const source = path.join(sourceRoot, name);
+        if (!fs.existsSync(source))
+            continue;
+        const target = path.join(skillDir, name);
+        await fs.promises.rm(target, { recursive: true, force: true });
+        await copyTree(source, target);
+    }
+}
+//# sourceMappingURL=skill-files.js.map

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

@@ -0,0 +1,49 @@
+/**
+ * Skill Generation Utilities
+ *
+ * Shared utilities for generating skill and command files.
+ */
+import type { SkillTemplate, CommandTemplate } from '../templates/types.js';
+import type { CommandContent } from '../command-generation/index.js';
+/**
+ * Skill template with directory name and workflow ID mapping.
+ */
+export interface SkillTemplateEntry {
+    template: SkillTemplate;
+    dirName: string;
+    workflowId: string;
+}
+/**
+ * Command template with ID mapping.
+ */
+export interface CommandTemplateEntry {
+    template: CommandTemplate;
+    id: string;
+}
+/**
+ * Gets skill templates with their directory names, optionally filtered by workflow IDs.
+ *
+ * @param workflowFilter - If provided, only return templates whose workflowId is in this array
+ */
+export declare function getSkillTemplates(workflowFilter?: readonly string[]): SkillTemplateEntry[];
+/**
+ * Gets command templates with their IDs, optionally filtered by workflow IDs.
+ *
+ * @param workflowFilter - If provided, only return templates whose id is in this array
+ */
+export declare function getCommandTemplates(workflowFilter?: readonly string[]): CommandTemplateEntry[];
+/**
+ * Converts command templates to CommandContent array, optionally filtered by workflow IDs.
+ *
+ * @param workflowFilter - If provided, only return contents whose id is in this array
+ */
+export declare function getCommandContents(workflowFilter?: readonly string[]): CommandContent[];
+/**
+ * Generates skill file content with YAML frontmatter.
+ *
+ * @param template - The skill template
+ * @param generatedByVersion - The FreeSpec version to embed in the file
+ * @param transformInstructions - Optional callback to transform the instructions content
+ */
+export declare function generateSkillContent(template: SkillTemplate, generatedByVersion: string, transformInstructions?: (instructions: string) => string): string;
+//# sourceMappingURL=skill-generation.d.ts.map

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

@@ -0,0 +1,125 @@
+/**
+ * Skill Generation Utilities
+ *
+ * Shared utilities for generating skill and command files.
+ */
+import { getAskCommandTemplate, getAskSkillTemplate, getCasesCommandTemplate, getCasesSkillTemplate, getCheckCommandTemplate, getCheckSkillTemplate, getDesignCommandTemplate, getDesignSkillTemplate, getJavaImplCommandTemplate, getJavaImplSkillTemplate, getJavaReviewCommandTemplate, getJavaReviewSkillTemplate, getNewCommandTemplate, getNewSkillTemplate, getRequirementsCommandTemplate, getRequirementsSkillTemplate, getReviewDocsCommandTemplate, getReviewDocsSkillTemplate, getTasksCommandTemplate, getTasksSkillTemplate, } from '../templates/workflows/personal.js';
+import { assertWorkflowConditionalsResolved, resolveOptionalWorkflows, } from '../templates/optional-workflow.js';
+import { ALL_WORKFLOWS } from '../profiles.js';
+import { OPENSPEC_CLI_ALLOWED_TOOLS } from './allowed-tools.js';
+/**
+ * The workflow set a template body is rendered against.
+ *
+ * `workflowFilter` is both the list of workflows to install and the set a
+ * template may refer to, so resolving optional-workflow conditionals here —
+ * the one place every generation path (init, update, migration, the skills.sh
+ * distribution) already funnels through — keeps a reference to an uninstalled
+ * workflow out of every generated file (#1734, umbrella #919).
+ *
+ * With no filter, every workflow is installed (that is what an unfiltered call
+ * means), so the installed branch is kept.
+ */
+function resolveInstalledWorkflows(workflowFilter) {
+    return new Set(workflowFilter ?? ALL_WORKFLOWS);
+}
+/**
+ * Gets skill templates with their directory names, optionally filtered by workflow IDs.
+ *
+ * @param workflowFilter - If provided, only return templates whose workflowId is in this array
+ */
+export function getSkillTemplates(workflowFilter) {
+    const all = [
+        { template: getNewSkillTemplate(), dirName: 'freespec-新建', workflowId: '新建' },
+        { template: getAskSkillTemplate(), dirName: 'freespec-深思', workflowId: '深思' },
+        { template: getRequirementsSkillTemplate(), dirName: 'freespec-需求', workflowId: '需求' },
+        { template: getDesignSkillTemplate(), dirName: 'freespec-设计', workflowId: '设计' },
+        { template: getTasksSkillTemplate(), dirName: 'freespec-任务', workflowId: '任务' },
+        { template: getReviewDocsSkillTemplate(), dirName: 'freespec-审文档', workflowId: '审文档' },
+        { template: getCasesSkillTemplate(), dirName: 'freespec-用例', workflowId: '用例' },
+        { template: getCheckSkillTemplate(), dirName: 'freespec-验收', workflowId: '验收' },
+        { template: getJavaImplSkillTemplate(), dirName: 'freespec-写Java', workflowId: '写Java' },
+        { template: getJavaReviewSkillTemplate(), dirName: 'freespec-审Java', workflowId: '审Java' },
+    ];
+    const installed = resolveInstalledWorkflows(workflowFilter);
+    const selected = workflowFilter ? all.filter(entry => installed.has(entry.workflowId)) : all;
+    return selected.map(entry => ({
+        ...entry,
+        template: {
+            ...entry.template,
+            instructions: resolveOptionalWorkflows(entry.template.instructions, installed),
+        },
+    }));
+}
+/**
+ * Gets command templates with their IDs, optionally filtered by workflow IDs.
+ *
+ * @param workflowFilter - If provided, only return templates whose id is in this array
+ */
+export function getCommandTemplates(workflowFilter) {
+    const all = [
+        { template: getNewCommandTemplate(), id: '新建' },
+        { template: getAskCommandTemplate(), id: '深思' },
+        { template: getRequirementsCommandTemplate(), id: '需求' },
+        { template: getDesignCommandTemplate(), id: '设计' },
+        { template: getTasksCommandTemplate(), id: '任务' },
+        { template: getReviewDocsCommandTemplate(), id: '审文档' },
+        { template: getCasesCommandTemplate(), id: '用例' },
+        { template: getCheckCommandTemplate(), id: '验收' },
+        { template: getJavaImplCommandTemplate(), id: '写Java' },
+        { template: getJavaReviewCommandTemplate(), id: '审Java' },
+    ];
+    const installed = resolveInstalledWorkflows(workflowFilter);
+    const selected = workflowFilter ? all.filter(entry => installed.has(entry.id)) : all;
+    return selected.map(entry => ({
+        ...entry,
+        template: {
+            ...entry.template,
+            content: resolveOptionalWorkflows(entry.template.content, installed),
+        },
+    }));
+}
+/**
+ * Converts command templates to CommandContent array, optionally filtered by workflow IDs.
+ *
+ * @param workflowFilter - If provided, only return contents whose id is in this array
+ */
+export function getCommandContents(workflowFilter) {
+    const commandTemplates = getCommandTemplates(workflowFilter);
+    return commandTemplates.map(({ template, id }) => ({
+        id,
+        name: template.name,
+        description: template.description,
+        category: template.category,
+        tags: template.tags,
+        body: template.content,
+    }));
+}
+/**
+ * Generates skill file content with YAML frontmatter.
+ *
+ * @param template - The skill template
+ * @param generatedByVersion - The FreeSpec version to embed in the file
+ * @param transformInstructions - Optional callback to transform the instructions content
+ */
+export function generateSkillContent(template, generatedByVersion, transformInstructions) {
+    const instructions = transformInstructions
+        ? transformInstructions(template.instructions)
+        : template.instructions;
+    assertWorkflowConditionalsResolved(instructions, `Skill '${template.name}' was generated without resolving its optional-workflow blocks`);
+    return `---
+name: ${template.name}
+description: ${template.description}
+disable-model-invocation: true
+allowed-tools: ${OPENSPEC_CLI_ALLOWED_TOOLS}
+license: ${template.license || 'MIT'}
+compatibility: ${template.compatibility || 'Requires freespec CLI.'}
+metadata:
+  author: ${template.metadata?.author || 'freespec'}
+  version: "${template.metadata?.version || '1.0'}"
+  generatedBy: "${generatedByVersion}"
+---
+
+${instructions}
+`;
+}
+//# sourceMappingURL=skill-generation.js.map

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

@@ -0,0 +1,13 @@
+import { type AIToolOption } from '../config.js';
+export type SkillCapableTool = AIToolOption & ({
+    skillsDir: string;
+} | {
+    globalSkillsDir: string;
+});
+export declare function toolSupportsSkills(tool: AIToolOption): tool is SkillCapableTool;
+export declare function getSkillCapableTools(): SkillCapableTool[];
+export declare function hasGlobalSkillTarget(tool: AIToolOption): boolean;
+export declare function resolveToolSkillsDir(projectRoot: string, tool: SkillCapableTool, options?: {
+    homeDir?: string;
+}): string;
+//# sourceMappingURL=skill-paths.d.ts.map