@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/utils/command-references.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Command Reference Utilities
+ *
+ * Utilities for transforming command references to tool-specific formats.
+ */
+import type { CommandSurfaceCapability } from '../core/command-surface.js';
+import type { CommandInvocation } from '../core/command-generation/invocation.js';
+/**
+ * Rewrites the canonical `/freespec:<command>` references that command bodies and
+ * skill templates are authored with into the form one tool actually registers
+ * — `/freespec-<command>` for tools that name the command by filename,
+ * `@freespec-<command>` for Amazon Q's prompt library.
+ *
+ * Only known command ids are rewritten, matching how
+ * `transformToSkillReferences` leaves unrecognized references alone, so a
+ * mistyped or invented `/freespec:<something>` is left as written rather than
+ * silently reshaped into a command that does not exist either.
+ *
+ * @param text - The text containing command references
+ * @param invocation - The tool's invocation, from resolveCommandInvocation()
+ * @returns Text with command references spelled the tool's way
+ *
+ * @example
+ * transformCommandInvocations('/freespec:new', { style: 'flat', prefix: '/' }) // '/freespec-new'
+ * transformCommandInvocations('/freespec:new', { style: 'flat', prefix: '@' }) // '@freespec-new'
+ */
+export declare function transformCommandInvocations(text: string, invocation: CommandInvocation): string;
+/**
+ * Whether a tool references skills by natural language rather than a slash
+ * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
+ */
+export declare function usesNaturalLanguageSkillReferences(toolId: string): boolean;
+/**
+ * Keeps Codex's `$<name>` spelling first while making its canonical shared
+ * `.agents` tree usable by agents that invoke the same skills with `/<name>`.
+ */
+export declare function transformToCodexCompatibleSkillReferences(text: string): string;
+/**
+ * Transforms command references to skill references using the default `/`
+ * invocation prefix. Converts `/freespec:<command>` patterns to
+ * `/freespec-<skill>` so that generated skills do not reference commands
+ * that were never generated. Used for channels that are not tied to one
+ * tool (e.g. the skills.sh distribution); tool-targeted generation should
+ * go through getSkillReferenceTransformer instead.
+ *
+ * Unknown command references are left unchanged.
+ *
+ * @param text - The text containing command references
+ * @returns Text with command references transformed to skill references
+ *
+ * @example
+ * transformToSkillReferences('/freespec:apply') // returns '/freespec-apply-change'
+ * transformToSkillReferences('Use /freespec:archive next') // returns 'Use /freespec-archive-change next'
+ */
+export declare function transformToSkillReferences(text: string): string;
+/**
+ * Returns the skill-reference transformer for a specific tool, honoring the
+ * tool's documented skill invocation syntax (e.g. Kimi Code's
+ * `/skill:freespec-propose`). Tools with no slash surface (e.g. Rovo Dev) get
+ * natural-language references ("the freespec-propose skill"); everything else
+ * falls back to the default `/freespec-*` form.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe', 'rovodev')
+ * @returns A transformer converting `/freespec:*` references to skill invocations
+ */
+export declare function getSkillReferenceTransformer(toolId: string): (text: string) => string;
+/**
+ * Selects the command-reference transformer for a skill generation target.
+ *
+ * Skill references are used whenever the tool ends up without `/freespec:*`
+ * commands — because delivery is skills-only, because the tool has no command
+ * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
+ * because the tool invokes skills directly and FreeSpec generates no command
+ * files for it (capability 'skills-invocable', e.g. Codex or Warp) — so those skills
+ * never point at commands that were not generated.
+ *
+ * When commands are generated, the spelling follows the tool's invocation: a
+ * `flat` adapter names the command by filename (`.cursor/commands/freespec-apply.md`
+ * → `/freespec-apply`), a `namespaced` adapter puts it in an `freespec/` directory
+ * (`.claude/commands/freespec/apply.md` → `/freespec:apply`), and a non-slash prefix
+ * wraps it further (`.amazonq/prompts/freespec-apply.md` → `@freespec-apply`). Passing
+ * the invocation in keeps this module free of a hand-maintained tool list —
+ * the list drifted and left 16 tools advertising commands their palettes never
+ * registered (#727, #1307).
+ *
+ * Devin is the one tool that takes skill references even though its commands
+ * are generated: only Devin Desktop reads `.devin/workflows/`, so a workflow
+ * reference is dead text for anyone on Devin Local, while the `/freespec-*`
+ * skills work on both agents. Under commands-only delivery there are no Devin
+ * skills to point at, so it falls through to the invocation rewrite below and
+ * gets the `/freespec-<id>` form its workflow filenames register.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'claude', 'opencode', 'pi')
+ * @param delivery - The configured delivery mode
+ * @param capability - The tool's command surface capability
+ * @param invocation - How the tool's generated commands are invoked, from
+ *        resolveCommandInvocation(); undefined for tools with no command
+ *        adapter. Required rather than optional so a caller that forgets it
+ *        fails to compile instead of silently getting the canonical form.
+ * @returns The transformer to pass to generateSkillContent, or undefined when
+ *          the tool already answers to the canonical `/freespec:<id>`
+ */
+export declare function getTransformerForTool(toolId: string, delivery: 'both' | 'skills' | 'commands', capability: CommandSurfaceCapability, invocation: CommandInvocation | undefined): ((text: string) => string) | undefined;
+//# sourceMappingURL=command-references.d.ts.map

package/dist/utils/command-references.js

@@ -0,0 +1,190 @@
+/**
+ * Command Reference Utilities
+ *
+ * Utilities for transforming command references to tool-specific formats.
+ */
+// Value import of a pure, dependency-free helper: invocation.ts imports only
+// `path` and a type, so this does not close the cycle the note above guards.
+import { formatCommandInvocation, needsInvocationRewrite, } from '../core/command-generation/invocation.js';
+/**
+ * Rewrites the canonical `/freespec:<command>` references that command bodies and
+ * skill templates are authored with into the form one tool actually registers
+ * — `/freespec-<command>` for tools that name the command by filename,
+ * `@freespec-<command>` for Amazon Q's prompt library.
+ *
+ * Only known command ids are rewritten, matching how
+ * `transformToSkillReferences` leaves unrecognized references alone, so a
+ * mistyped or invented `/freespec:<something>` is left as written rather than
+ * silently reshaped into a command that does not exist either.
+ *
+ * @param text - The text containing command references
+ * @param invocation - The tool's invocation, from resolveCommandInvocation()
+ * @returns Text with command references spelled the tool's way
+ *
+ * @example
+ * transformCommandInvocations('/freespec:new', { style: 'flat', prefix: '/' }) // '/freespec-new'
+ * transformCommandInvocations('/freespec:new', { style: 'flat', prefix: '@' }) // '@freespec-new'
+ */
+export function transformCommandInvocations(text, invocation) {
+    return text.replace(/\/freespec:([a-zA-Z0-9\u4e00-\u9fff-]+)/g, (match, commandId) => commandId in COMMAND_TO_SKILL_NAME
+        ? formatCommandInvocation(invocation, commandId)
+        : match);
+}
+/**
+ * Maps command short names to their skill names.
+ * Keep in sync with WORKFLOW_TO_SKILL_DIR, which exists in both
+ * src/core/profile-sync-drift.ts (exported) and src/core/init.ts (local copy).
+ */
+const COMMAND_TO_SKILL_NAME = {
+    '新建': '新建',
+    '深思': '深思',
+    '需求': '需求',
+    '设计': '设计',
+    '任务': '任务',
+    '审文档': '审文档',
+    '用例': '用例',
+    '验收': '验收',
+    '写Java': '写Java',
+    '审Java': '审Java',
+};
+/**
+ * Tools whose skill invocation uses a non-default prefix. The default is `/`
+ * (e.g. `/freespec-propose`); Kimi Code invokes skills as `/skill:<name>` and
+ * Codex CLI as `$<name>` — a `/<name>` form Codex does not recognize
+ * (see docs/supported-tools.md).
+ */
+const SKILL_INVOCATION_PREFIX = {
+    kimi: '/skill:',
+    codex: '$',
+};
+/**
+ * Tools with no documented slash invocation for skills: use automatic
+ * matching or natural-language prompts instead. SourceCraft Code Assistant
+ * supports separate command files, but its skills use description matching.
+ * Rovo Dev's `/skills` only manages skills (see docs/supported-tools.md).
+ * Skill references for these tools are spelled as prose ("the freespec-propose
+ * skill") so skills-only delivery does not advertise unregistered commands.
+ */
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['gsd', 'rovodev', 'codeassistant']);
+/**
+ * Whether a tool references skills by natural language rather than a slash
+ * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
+ */
+export function usesNaturalLanguageSkillReferences(toolId) {
+    return NATURAL_LANGUAGE_SKILL_TOOLS.has(toolId);
+}
+function replaceCommandsWithNaturalLanguageSkillReferences(text) {
+    return text.replace(/\/freespec:([a-zA-Z0-9\u4e00-\u9fff-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined ? match : `the ${skillName} skill`;
+    });
+}
+function replaceCommandsWithSkillReferences(text, prefix) {
+    return text.replace(/\/freespec:([a-zA-Z0-9\u4e00-\u9fff-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined ? match : `${prefix}${skillName}`;
+    });
+}
+/**
+ * Keeps Codex's `$<name>` spelling first while making its canonical shared
+ * `.agents` tree usable by agents that invoke the same skills with `/<name>`.
+ */
+export function transformToCodexCompatibleSkillReferences(text) {
+    return text.replace(/\/freespec:([a-zA-Z0-9\u4e00-\u9fff-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined
+            ? match
+            : `$${skillName} (Codex) or /${skillName} (other agents)`;
+    });
+}
+/**
+ * Transforms command references to skill references using the default `/`
+ * invocation prefix. Converts `/freespec:<command>` patterns to
+ * `/freespec-<skill>` so that generated skills do not reference commands
+ * that were never generated. Used for channels that are not tied to one
+ * tool (e.g. the skills.sh distribution); tool-targeted generation should
+ * go through getSkillReferenceTransformer instead.
+ *
+ * Unknown command references are left unchanged.
+ *
+ * @param text - The text containing command references
+ * @returns Text with command references transformed to skill references
+ *
+ * @example
+ * transformToSkillReferences('/freespec:apply') // returns '/freespec-apply-change'
+ * transformToSkillReferences('Use /freespec:archive next') // returns 'Use /freespec-archive-change next'
+ */
+export function transformToSkillReferences(text) {
+    return replaceCommandsWithSkillReferences(text, '/');
+}
+/**
+ * Returns the skill-reference transformer for a specific tool, honoring the
+ * tool's documented skill invocation syntax (e.g. Kimi Code's
+ * `/skill:freespec-propose`). Tools with no slash surface (e.g. Rovo Dev) get
+ * natural-language references ("the freespec-propose skill"); everything else
+ * falls back to the default `/freespec-*` form.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe', 'rovodev')
+ * @returns A transformer converting `/freespec:*` references to skill invocations
+ */
+export function getSkillReferenceTransformer(toolId) {
+    if (usesNaturalLanguageSkillReferences(toolId)) {
+        return replaceCommandsWithNaturalLanguageSkillReferences;
+    }
+    const prefix = SKILL_INVOCATION_PREFIX[toolId];
+    if (prefix === undefined) {
+        return transformToSkillReferences;
+    }
+    return (text) => replaceCommandsWithSkillReferences(text, prefix);
+}
+/**
+ * Selects the command-reference transformer for a skill generation target.
+ *
+ * Skill references are used whenever the tool ends up without `/freespec:*`
+ * commands — because delivery is skills-only, because the tool has no command
+ * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
+ * because the tool invokes skills directly and FreeSpec generates no command
+ * files for it (capability 'skills-invocable', e.g. Codex or Warp) — so those skills
+ * never point at commands that were not generated.
+ *
+ * When commands are generated, the spelling follows the tool's invocation: a
+ * `flat` adapter names the command by filename (`.cursor/commands/freespec-apply.md`
+ * → `/freespec-apply`), a `namespaced` adapter puts it in an `freespec/` directory
+ * (`.claude/commands/freespec/apply.md` → `/freespec:apply`), and a non-slash prefix
+ * wraps it further (`.amazonq/prompts/freespec-apply.md` → `@freespec-apply`). Passing
+ * the invocation in keeps this module free of a hand-maintained tool list —
+ * the list drifted and left 16 tools advertising commands their palettes never
+ * registered (#727, #1307).
+ *
+ * Devin is the one tool that takes skill references even though its commands
+ * are generated: only Devin Desktop reads `.devin/workflows/`, so a workflow
+ * reference is dead text for anyone on Devin Local, while the `/freespec-*`
+ * skills work on both agents. Under commands-only delivery there are no Devin
+ * skills to point at, so it falls through to the invocation rewrite below and
+ * gets the `/freespec-<id>` form its workflow filenames register.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'claude', 'opencode', 'pi')
+ * @param delivery - The configured delivery mode
+ * @param capability - The tool's command surface capability
+ * @param invocation - How the tool's generated commands are invoked, from
+ *        resolveCommandInvocation(); undefined for tools with no command
+ *        adapter. Required rather than optional so a caller that forgets it
+ *        fails to compile instead of silently getting the canonical form.
+ * @returns The transformer to pass to generateSkillContent, or undefined when
+ *          the tool already answers to the canonical `/freespec:<id>`
+ */
+export function getTransformerForTool(toolId, delivery, capability, invocation) {
+    if (delivery === 'skills' || capability !== 'adapter-backed') {
+        return toolId === 'codex'
+            ? transformToCodexCompatibleSkillReferences
+            : getSkillReferenceTransformer(toolId);
+    }
+    if (toolId === 'devin' && delivery === 'both') {
+        return getSkillReferenceTransformer(toolId);
+    }
+    if (invocation !== undefined && needsInvocationRewrite(invocation)) {
+        return (text) => transformCommandInvocations(text, invocation);
+    }
+    return undefined;
+}
+//# sourceMappingURL=command-references.js.map

package/dist/utils/date.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats a date using the effective local time zone of the Node.js process.
+ *
+ * The result is locale-independent and suitable for date-only metadata and
+ * path prefixes.
+ */
+export declare function formatLocalDate(date?: Date): string;
+//# sourceMappingURL=date.d.ts.map

package/dist/utils/date.js

@@ -0,0 +1,13 @@
+/**
+ * Formats a date using the effective local time zone of the Node.js process.
+ *
+ * The result is locale-independent and suitable for date-only metadata and
+ * path prefixes.
+ */
+export function formatLocalDate(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+//# sourceMappingURL=date.js.map

package/dist/utils/executable-path.d.ts

@@ -0,0 +1,5 @@
+/** Every `freespec` on PATH, in the order a shell would find them. */
+export declare function findCopiesOnPath(pathValue?: string, platform?: NodeJS.Platform): string[];
+/** Whether two paths name the same file once symlinks are resolved. */
+export declare function samePath(a: string, b: string): boolean;
+//# sourceMappingURL=executable-path.d.ts.map

package/dist/utils/executable-path.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Every `freespec` on PATH, in the order a shell would find them. */
+export function findCopiesOnPath(pathValue = process.env.PATH ?? '', platform = process.platform) {
+    const names = platform === 'win32' ? ['freespec.exe', 'freespec.cmd'] : ['freespec'];
+    const seen = new Set();
+    const copies = [];
+    for (const dir of pathValue.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            try {
+                if (!fs.statSync(candidate).isFile())
+                    continue;
+                if (platform !== 'win32')
+                    fs.accessSync(candidate, fs.constants.X_OK);
+                const key = platform === 'win32' ? candidate.toLowerCase() : candidate;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    copies.push(candidate);
+                }
+            }
+            catch {
+                // Not there, or not runnable: not a copy a shell would run.
+            }
+        }
+    }
+    return copies;
+}
+/** Whether two paths name the same file once symlinks are resolved. */
+export function samePath(a, b) {
+    const real = (value) => {
+        try {
+            return fs.realpathSync(value);
+        }
+        catch {
+            return path.resolve(value);
+        }
+    };
+    const [x, y] = [real(a), real(b)];
+    return process.platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
+//# sourceMappingURL=executable-path.js.map

package/dist/utils/file-system.d.ts

@@ -0,0 +1,58 @@
+export declare class FileSystemUtils {
+    /**
+     * Converts a path to use forward slashes (POSIX style).
+     * Essential for cross-platform compatibility with glob libraries like tinyglobby.
+     */
+    static toPosixPath(p: string): string;
+    /**
+     * Returns a canonical absolute path when the target exists.
+     * Falls back to path.resolve() so callers can still produce a stable absolute path.
+     */
+    static canonicalizeExistingPath(targetPath: string): string;
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory: string, targetPath: string): void;
+    /**
+     * Like assertPathWithin, but a targetPath that is itself a symlink may
+     * resolve outside allowedDirectory, so a project can keep a managed
+     * directory (for example freespec) in another repository. Its parent
+     * must still be confined and the link must resolve to an existing path.
+     */
+    static assertPathWithinAllowingLinkedLeaf(allowedDirectory: string, targetPath: string): void;
+    static resolveProjectArtifactPath(projectPath: string, artifactPath: string): string;
+    static assertProjectArtifactPath(projectPath: string, targetPath: string): void;
+    private static isPathWithin;
+    private static canonicalizePotentialPath;
+    private static isWindowsBasePath;
+    private static normalizeSegments;
+    static joinPath(basePath: string, ...segments: string[]): string;
+    static createDirectory(dirPath: string): Promise<void>;
+    static fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Finds the first existing parent directory by walking up the directory tree.
+     * @param dirPath Starting directory path
+     * @returns The first existing directory path, or null if root is reached without finding one
+     */
+    private static findFirstExistingDirectory;
+    static canWriteFile(filePath: string): Promise<boolean>;
+    static directoryExists(dirPath: string): Promise<boolean>;
+    static writeFile(filePath: string, content: string): Promise<void>;
+    static readFile(filePath: string): Promise<string>;
+    static updateFileWithMarkers(filePath: string, content: string, startMarker: string, endMarker: string): Promise<void>;
+    static ensureWritePermissions(dirPath: string): Promise<boolean>;
+}
+/**
+ * Removes a marker block from file content.
+ * Only removes markers that are on their own lines (ignores inline mentions).
+ * Cleans up double blank lines that may result from removal.
+ *
+ * @param content - File content with markers
+ * @param startMarker - The start marker string
+ * @param endMarker - The end marker string
+ * @returns Content with marker block removed, or original content if markers not found/invalid
+ */
+export declare function removeMarkerBlock(content: string, startMarker: string, endMarker: string): string;
+//# sourceMappingURL=file-system.d.ts.map