@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/utils/change-metadata.d.ts

@@ -0,0 +1,116 @@
+import { CHANGE_METADATA_KNOWN_KEYS, type ChangeMetadata } from '../core/change-metadata/index.js';
+import { type ProjectConfig } from '../core/project-config.js';
+export declare const METADATA_FILENAME = ".freespec.yaml";
+export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Extension keys: a top-level key starting with a lowercase `x-` belongs to a
+ * tool or team that reads `.freespec.yaml` alongside FreeSpec (a tracker id, an
+ * owner). FreeSpec ignores it and does not report it as unknown. As with
+ * OpenAPI's `x-` extensions, the name after the prefix may use any case or
+ * spelling, but must be non-empty and free of whitespace, so `x-`, `x- foo`
+ * and `X-Foo` are still reported. Extensions are top-level only: a key inside
+ * `initiative:` is rejected by that object's strict schema.
+ */
+export declare const EXTENSION_KEY_PATTERN: RegExp;
+export declare function isExtensionMetadataKey(key: string): boolean;
+/**
+ * Unknown top-level keys on a parsed .freespec.yaml object. Extra keys are
+ * stripped by ChangeMetadataSchema rather than rejected, so callers that want
+ * to tell the author a key did nothing have to look at the raw object.
+ * Extension keys (`x-*`) are not unknown: they are deliberately someone else's.
+ */
+export declare function listUnknownChangeMetadataKeys(parsed: unknown): string[];
+/**
+ * Human-readable warning for keys ChangeMetadataSchema strips. Names the
+ * unknown keys and the keys that do exist.
+ */
+export declare function formatUnknownChangeMetadataKeysMessage(keys: string[]): string;
+/**
+ * Non-throwing read of unknown top-level keys. Missing, unreadable, or
+ * unparseable files yield no keys: those failures already have their own
+ * diagnostics on the read path.
+ */
+export declare function readUnknownChangeMetadataKeys(changeDir: string): string[];
+/**
+ * Error thrown when change metadata validation fails.
+ */
+export declare class ChangeMetadataError extends Error {
+    readonly metadataPath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, metadataPath: string, cause?: Error | undefined);
+}
+/**
+ * Validates that a schema name is valid (exists in available schemas).
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The validated schema name
+ * @throws Error if schema is not found
+ */
+export declare function validateSchemaName(schemaName: string, projectRoot?: string): string;
+/**
+ * Writes change metadata to .freespec.yaml in the change directory.
+ *
+ * Meant for a new file only (`createChange` refuses an existing change
+ * directory). `ChangeMetadataSchema` strips unknown keys, including `x-`
+ * extension keys, so a caller that rewrites an existing file must merge those
+ * keys back from the raw YAML first or it silently deletes them.
+ *
+ * @param changeDir - The path to the change directory
+ * @param metadata - The metadata to write
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @throws ChangeMetadataError if validation fails or write fails
+ */
+export declare function writeChangeMetadata(changeDir: string, metadata: ChangeMetadata, projectRoot?: string): void;
+/**
+ * Reads change metadata from .freespec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The validated metadata, or null if no metadata file exists
+ * @throws ChangeMetadataError if the file exists but is invalid
+ */
+export declare function readChangeMetadata(changeDir: string, projectRoot?: string): ChangeMetadata | null;
+export interface ResolveSchemaForChangeOptions {
+    metadata?: ChangeMetadata | null;
+    /** Pre-read project config; suppresses the fallback config read when provided. */
+    projectConfig?: ProjectConfig | null;
+}
+/**
+ * Resolves the schema for a change, with explicit override taking precedence.
+ *
+ * Resolution order:
+ * 1. Explicit schema (if provided)
+ * 2. Schema from .freespec.yaml metadata (if exists)
+ * 3. Schema from freespec/config.yaml (if exists)
+ * 4. Default schema (`默认`)
+ *
+ * @param changeDir - The path to the change directory
+ * @param explicitSchema - Optional explicit schema override
+ * @returns The resolved schema name
+ */
+export declare function resolveSchemaForChange(changeDir: string, explicitSchema?: string, projectRootOverride?: string, options?: ResolveSchemaForChangeOptions): string;
+export interface MetadataMarker {
+    /**
+     * True when the metadata parses under ChangeMetadataSchema, sets
+     * the requested boolean marker to true, and names a schema that loads.
+     */
+    declared: boolean;
+    /**
+     * Set when the marker cannot be honored: it appears in a file that
+     * fails the metadata contract, or the metadata file exists but cannot be
+     * read at all (so whether the marker is set cannot even be determined).
+     */
+    invalidReason?: string;
+}
+/**
+ * Non-throwing read of the retire_capabilities marker.
+ *
+ * Gates the one archive action that removes a file from `freespec/specs/`: when
+ * a change's REMOVED entries take a capability's last requirement, archive
+ * deletes the emptied main spec rather than aborting on a spec it cannot write
+ * (#1302). Declared rather than inferred because the delete is recoverable only
+ * from git, so it is the author's call.
+ */
+export declare function readRetireCapabilitiesMarker(changeDir: string): MetadataMarker;
+//# sourceMappingURL=change-metadata.d.ts.map

package/dist/utils/change-metadata.js

@@ -0,0 +1,324 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { CHANGE_METADATA_KNOWN_KEYS, ChangeMetadataSchema, } from '../core/change-metadata/index.js';
+import { listSchemas, resolveSchema } from '../core/artifact-graph/resolver.js';
+import { readProjectConfig } from '../core/project-config.js';
+import { sanitizeInline } from '../core/references.js';
+import { DEFAULT_SCHEMA } from '../core/change-layout.js';
+export const METADATA_FILENAME = '.freespec.yaml';
+export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Extension keys: a top-level key starting with a lowercase `x-` belongs to a
+ * tool or team that reads `.freespec.yaml` alongside FreeSpec (a tracker id, an
+ * owner). FreeSpec ignores it and does not report it as unknown. As with
+ * OpenAPI's `x-` extensions, the name after the prefix may use any case or
+ * spelling, but must be non-empty and free of whitespace, so `x-`, `x- foo`
+ * and `X-Foo` are still reported. Extensions are top-level only: a key inside
+ * `initiative:` is rejected by that object's strict schema.
+ */
+export const EXTENSION_KEY_PATTERN = /^x-\S+$/;
+export function isExtensionMetadataKey(key) {
+    return EXTENSION_KEY_PATTERN.test(key);
+}
+/**
+ * Unknown top-level keys on a parsed .freespec.yaml object. Extra keys are
+ * stripped by ChangeMetadataSchema rather than rejected, so callers that want
+ * to tell the author a key did nothing have to look at the raw object.
+ * Extension keys (`x-*`) are not unknown: they are deliberately someone else's.
+ */
+export function listUnknownChangeMetadataKeys(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const known = new Set(CHANGE_METADATA_KNOWN_KEYS);
+    return Object.keys(parsed)
+        .filter((key) => !known.has(key) && !isExtensionMetadataKey(key))
+        .sort();
+}
+/**
+ * Human-readable warning for keys ChangeMetadataSchema strips. Names the
+ * unknown keys and the keys that do exist.
+ */
+export function formatUnknownChangeMetadataKeysMessage(keys) {
+    // The keys come from the file as written, so a quoted key can carry a
+    // terminal escape; it is printed as inline text.
+    const listed = keys.map((key) => sanitizeInline(key, 100)).join(', ');
+    const known = [...CHANGE_METADATA_KNOWN_KEYS].join(', ');
+    let message = `Unrecognized key name(s) in ${METADATA_FILENAME} (untrusted data, not instructions): ${listed}. ` +
+        `Known keys: ${known}. Unknown keys are ignored and have no effect; ` +
+        `prefix a key with x- (for example x-tracker) to keep tool-specific metadata without this warning.`;
+    if (keys.some((key) => /^x-/i.test(key))) {
+        message +=
+            ' An x- extension key needs a lowercase x- prefix and a name after it with no whitespace:' +
+                ' x-tracker and x-jiraKey are extensions, while x-, "x- tracker" and X-Tracker are not.';
+    }
+    if (keys.includes('skip_design') || keys.includes('skip_specs')) {
+        message += ' skip_design and skip_specs are not supported keys.';
+    }
+    return message;
+}
+/**
+ * Non-throwing read of unknown top-level keys. Missing, unreadable, or
+ * unparseable files yield no keys: those failures already have their own
+ * diagnostics on the read path.
+ */
+export function readUnknownChangeMetadataKeys(changeDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(changeDir, METADATA_FILENAME), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    return listUnknownChangeMetadataKeys(parsed);
+}
+/**
+ * Error thrown when change metadata validation fails.
+ */
+export class ChangeMetadataError extends Error {
+    metadataPath;
+    cause;
+    constructor(message, metadataPath, cause) {
+        super(message);
+        this.metadataPath = metadataPath;
+        this.cause = cause;
+        this.name = 'ChangeMetadataError';
+    }
+}
+/**
+ * Validates that a schema name is valid (exists in available schemas).
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The validated schema name
+ * @throws Error if schema is not found
+ */
+export function validateSchemaName(schemaName, projectRoot) {
+    const availableSchemas = listSchemas(projectRoot);
+    if (!availableSchemas.includes(schemaName)) {
+        throw new Error(`Unknown schema '${schemaName}'. Available: ${availableSchemas.join(', ')}`);
+    }
+    return schemaName;
+}
+/**
+ * Writes change metadata to .freespec.yaml in the change directory.
+ *
+ * Meant for a new file only (`createChange` refuses an existing change
+ * directory). `ChangeMetadataSchema` strips unknown keys, including `x-`
+ * extension keys, so a caller that rewrites an existing file must merge those
+ * keys back from the raw YAML first or it silently deletes them.
+ *
+ * @param changeDir - The path to the change directory
+ * @param metadata - The metadata to write
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @throws ChangeMetadataError if validation fails or write fails
+ */
+export function writeChangeMetadata(changeDir, metadata, projectRoot) {
+    const metaPath = path.join(changeDir, METADATA_FILENAME);
+    // Validate schema exists
+    validateSchemaName(metadata.schema, projectRoot);
+    // Validate with Zod
+    const parseResult = ChangeMetadataSchema.safeParse(metadata);
+    if (!parseResult.success) {
+        throw new ChangeMetadataError(`Invalid metadata: ${parseResult.error.message}`, metaPath);
+    }
+    // Write YAML file
+    const content = yaml.stringify(parseResult.data);
+    try {
+        fs.writeFileSync(metaPath, content, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Failed to write metadata: ${ioError.message}`, metaPath, ioError);
+    }
+}
+/**
+ * Reads change metadata from .freespec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The validated metadata, or null if no metadata file exists
+ * @throws ChangeMetadataError if the file exists but is invalid
+ */
+export function readChangeMetadata(changeDir, projectRoot) {
+    const metaPath = path.join(changeDir, METADATA_FILENAME);
+    if (!fs.existsSync(metaPath)) {
+        return null;
+    }
+    let content;
+    try {
+        content = fs.readFileSync(metaPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Failed to read metadata: ${ioError.message}`, metaPath, ioError);
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(content);
+    }
+    catch (err) {
+        const parseError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Invalid YAML in metadata file: ${parseError.message}`, metaPath, parseError);
+    }
+    // Validate with Zod
+    const parseResult = ChangeMetadataSchema.safeParse(parsed);
+    if (!parseResult.success) {
+        throw new ChangeMetadataError(`Invalid metadata: ${parseResult.error.message}`, metaPath);
+    }
+    // Validate that the schema exists
+    const availableSchemas = listSchemas(projectRoot);
+    if (!availableSchemas.includes(parseResult.data.schema)) {
+        throw new ChangeMetadataError(`Unknown schema '${parseResult.data.schema}'. Available: ${availableSchemas.join(', ')}`, metaPath);
+    }
+    return parseResult.data;
+}
+/**
+ * Resolves the schema for a change, with explicit override taking precedence.
+ *
+ * Resolution order:
+ * 1. Explicit schema (if provided)
+ * 2. Schema from .freespec.yaml metadata (if exists)
+ * 3. Schema from freespec/config.yaml (if exists)
+ * 4. Default schema (`默认`)
+ *
+ * @param changeDir - The path to the change directory
+ * @param explicitSchema - Optional explicit schema override
+ * @returns The resolved schema name
+ */
+export function resolveSchemaForChange(changeDir, explicitSchema, projectRootOverride, options = {}) {
+    // Change directories sit directly under freespec/: projectRoot/freespec/<名称>变更
+    const projectRoot = projectRootOverride ?? path.resolve(changeDir, '../..');
+    // 1. Explicit override wins
+    if (explicitSchema) {
+        return explicitSchema;
+    }
+    const metadata = options.metadata !== undefined ? options.metadata : readChangeMetadata(changeDir, projectRoot);
+    if (metadata?.schema) {
+        return metadata.schema;
+    }
+    // 3. Try reading from project config when metadata is absent.
+    if (options.projectConfig !== undefined) {
+        if (options.projectConfig?.schema) {
+            return options.projectConfig.schema;
+        }
+    }
+    else {
+        try {
+            const config = readProjectConfig(projectRoot);
+            if (config?.schema) {
+                return config.schema;
+            }
+        }
+        catch {
+            // If config read fails, fall back to default
+        }
+    }
+    // 4. Default
+    return DEFAULT_SCHEMA;
+}
+/**
+ * Non-throwing read of the retire_capabilities marker.
+ *
+ * Gates the one archive action that removes a file from `freespec/specs/`: when
+ * a change's REMOVED entries take a capability's last requirement, archive
+ * deletes the emptied main spec rather than aborting on a spec it cannot write
+ * (#1302). Declared rather than inferred because the delete is recoverable only
+ * from git, so it is the author's call.
+ */
+export function readRetireCapabilitiesMarker(changeDir) {
+    return readBooleanMarker(changeDir, 'retire_capabilities');
+}
+/**
+ * Shared implementation for the boolean change-metadata markers, keyed by field
+ * name. One body rather than two, so a marker can never drift into honoring
+ * metadata the other rejects - the whole point of the contract described above.
+ */
+/**
+ * A marker that cannot be honored, with its reason made safe to print.
+ *
+ * Every reason quotes something the author wrote - a schema name, a parser
+ * message carrying one, a filesystem error carrying a path - and callers print
+ * it straight to a terminal (`freespec archive`, `freespec validate`). A raw CR
+ * could forge a line of its own and an ESC could redraw the screen, so control
+ * characters never leave this function.
+ */
+function unhonorable(reason) {
+    return { declared: false, invalidReason: reason.replace(/[\u0000-\u001f\u007f]/g, '?') };
+}
+function readBooleanMarker(changeDir, key) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(changeDir, METADATA_FILENAME), 'utf-8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return { declared: false };
+        }
+        // The file exists but cannot be read (EACCES, EISDIR, ...). Status and
+        // instructions reject the change outright here, and whether a marker is
+        // set cannot be determined - fail closed rather than let archive treat
+        // the change as unmarked while every metadata-reading surface errors.
+        const message = err instanceof Error ? err.message : String(err);
+        return unhonorable(`the metadata file cannot be read (${message})`);
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        // Anchored so a comment like "# maybe add skip_specs later" does not
+        // claim the marker was set.
+        const mentioned = new RegExp(`^\\s*(['"]?)${key}\\1\\s*:`, 'm').test(raw);
+        return mentioned ? unhonorable('the file is not valid YAML') : { declared: false };
+    }
+    const result = ChangeMetadataSchema.safeParse(parsed);
+    if (result.success) {
+        if (result.data[key] !== true) {
+            return { declared: false };
+        }
+        // Schema loading is checked only when the marker is set: a broken schema
+        // on an ordinary change is status's problem to report, but honoring a
+        // marker that status rejects would let validate/archive pass what the
+        // rest of the CLI refuses to load. The membership check mirrors
+        // readChangeMetadata (which rejects names like 'spec-driven.yaml' that
+        // resolveSchema alone would normalize and accept); resolveSchema then
+        // proves the schema actually parses. Any failure fails closed.
+        try {
+            const projectRoot = path.resolve(changeDir, '../..');
+            if (!listSchemas(projectRoot).includes(result.data.schema)) {
+                return unhonorable(`schema: unknown schema '${result.data.schema}'`);
+            }
+            resolveSchema(result.data.schema, projectRoot);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return unhonorable(message);
+        }
+        return { declared: true };
+    }
+    // Key presence, not value: skip_specs: "yes" must surface as unhonorable,
+    // not vanish while the zero-delta guidance tells the user to set the very
+    // marker they set. An explicit skip_specs: false is the opposite of setting
+    // the marker, so it must not drag unrelated metadata problems into
+    // validate - the change simply is not marked.
+    const markerMentioned = typeof parsed === 'object' &&
+        parsed !== null &&
+        key in parsed &&
+        parsed[key] !== false;
+    if (markerMentioned) {
+        const first = result.error.issues[0];
+        const where = first.path.length > 0 ? `${first.path.join('.')}: ` : '';
+        return unhonorable(`${where}${first.message}`);
+    }
+    return { declared: false };
+}
+//# sourceMappingURL=change-metadata.js.map

package/dist/utils/change-utils.d.ts

@@ -0,0 +1,79 @@
+import type { ChangeMetadata } from '../core/change-metadata/index.js';
+/**
+ * Options for creating a change.
+ */
+export interface CreateChangeOptions {
+    /** The workflow schema to use (default: 默认) */
+    schema?: string;
+    /** Default schema to use when no explicit schema or project config is present */
+    defaultSchema?: string;
+    /** Directory that should contain the change directories */
+    changesDir?: string;
+    /** Additional metadata to persist in the change's .freespec.yaml */
+    metadata?: Partial<Pick<ChangeMetadata, 'goal' | 'affected_areas' | 'initiative'>>;
+}
+/**
+ * Result of creating a change.
+ */
+export interface CreateChangeResult {
+    /** The schema that was actually used (resolved from options, config, or default) */
+    schema: string;
+    /** Folder name under freespec/, including the 变更 suffix */
+    changeName: string;
+    /** Absolute path to the created change directory */
+    changeDir: string;
+}
+/**
+ * Result of validating a change name.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validates that a change name follows kebab-case conventions.
+ *
+ * Uses FreeSpec's shared kebab-id grammar (the same one store ids and change
+ * metadata ids use), so a change name may:
+ * - Start with a lowercase letter or a digit
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Not start or end with a hyphen
+ * - Not contain consecutive hyphens
+ *
+ * A leading digit is allowed so ordering conventions like `100-add-feature` or
+ * `00001-add-auth` work; archive already treats such prefixes as a supported
+ * convention (see ARCHIVE_DATE_PREFIX_PATTERN).
+ *
+ * @param name - The change name to validate
+ * @returns Validation result with `valid: true` or `valid: false` with an error message
+ *
+ * @example
+ * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('100-add-feature') // { valid: true }
+ * validateChangeName('Add-Auth') // { valid: false, error: '...' }
+ */
+export declare function validateChangeName(name: string): ValidationResult;
+/**
+ * Creates a new change directory with metadata file.
+ *
+ * @param projectRoot - The root directory of the project (where `freespec/` lives)
+ * @param name - The change name (must be valid kebab-case)
+ * @param options - Optional settings for the change
+ * @throws Error if the change name is invalid
+ * @throws Error if the schema name is invalid
+ * @throws Error if the change directory already exists
+ *
+ * @returns Result containing the resolved schema name
+ *
+ * @example
+ * // Creates freespec/登录改造变更/ with default schema
+ * const result = await createChange('/path/to/project', 'add-auth')
+ * console.log(result.schema) // '默认' or value from config
+ *
+ * @example
+ * // Creates freespec/登录改造变更/ with custom schema
+ * const result = await createChange('/path/to/project', 'add-auth', { schema: 'my-workflow' })
+ * console.log(result.schema) // 'my-workflow'
+ */
+export declare function createChange(projectRoot: string, name: string, options?: CreateChangeOptions): Promise<CreateChangeResult>;
+//# sourceMappingURL=change-utils.d.ts.map

package/dist/utils/change-utils.js

@@ -0,0 +1,121 @@
+import path from 'path';
+import { FileSystemUtils } from './file-system.js';
+import { writeChangeMetadata, validateSchemaName } from './change-metadata.js';
+import { formatLocalDate } from './date.js';
+import { readProjectConfig } from '../core/project-config.js';
+import { changeParentDir, DEFAULT_SCHEMA, isChangeDirectoryName, normalizeChangeName, } from '../core/change-layout.js';
+/**
+ * Validates that a change name follows kebab-case conventions.
+ *
+ * Uses FreeSpec's shared kebab-id grammar (the same one store ids and change
+ * metadata ids use), so a change name may:
+ * - Start with a lowercase letter or a digit
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Not start or end with a hyphen
+ * - Not contain consecutive hyphens
+ *
+ * A leading digit is allowed so ordering conventions like `100-add-feature` or
+ * `00001-add-auth` work; archive already treats such prefixes as a supported
+ * convention (see ARCHIVE_DATE_PREFIX_PATTERN).
+ *
+ * @param name - The change name to validate
+ * @returns Validation result with `valid: true` or `valid: false` with an error message
+ *
+ * @example
+ * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('100-add-feature') // { valid: true }
+ * validateChangeName('Add-Auth') // { valid: false, error: '...' }
+ */
+export function validateChangeName(name) {
+    const folderName = normalizeChangeName(name);
+    if (!folderName) {
+        return { valid: false, error: '变更名不能为空' };
+    }
+    if (folderName.length > 80) {
+        return { valid: false, error: '变更名太长（最多 80 个字符）' };
+    }
+    if (/\s/u.test(folderName)) {
+        return { valid: false, error: '变更名不能包含空格，用连字符连接' };
+    }
+    if (!isChangeDirectoryName(folderName)) {
+        return {
+            valid: false,
+            error: '变更名用中文，可以加数字和连字符，并以「变更」结尾。例如：登录改造变更',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Creates a new change directory with metadata file.
+ *
+ * @param projectRoot - The root directory of the project (where `freespec/` lives)
+ * @param name - The change name (must be valid kebab-case)
+ * @param options - Optional settings for the change
+ * @throws Error if the change name is invalid
+ * @throws Error if the schema name is invalid
+ * @throws Error if the change directory already exists
+ *
+ * @returns Result containing the resolved schema name
+ *
+ * @example
+ * // Creates freespec/登录改造变更/ with default schema
+ * const result = await createChange('/path/to/project', 'add-auth')
+ * console.log(result.schema) // '默认' or value from config
+ *
+ * @example
+ * // Creates freespec/登录改造变更/ with custom schema
+ * const result = await createChange('/path/to/project', 'add-auth', { schema: 'my-workflow' })
+ * console.log(result.schema) // 'my-workflow'
+ */
+export async function createChange(projectRoot, name, options = {}) {
+    // Validate the name first
+    const folderName = normalizeChangeName(name);
+    const validation = validateChangeName(folderName);
+    if (!validation.valid) {
+        throw new Error(validation.error);
+    }
+    const defaultSchema = options.defaultSchema ?? DEFAULT_SCHEMA;
+    // Determine schema: explicit option → project config → supplied default
+    let schemaName;
+    if (options.schema) {
+        schemaName = options.schema;
+    }
+    else {
+        // Try to read from project config
+        try {
+            const config = readProjectConfig(projectRoot);
+            schemaName = config?.schema ?? defaultSchema;
+        }
+        catch {
+            // If config read fails, use default
+            schemaName = defaultSchema;
+        }
+    }
+    // Validate the resolved schema
+    validateSchemaName(schemaName, projectRoot);
+    // Build the change directory path
+    const changeDir = path.join(options.changesDir ?? changeParentDir(projectRoot), folderName);
+    // Check if change already exists
+    if (await FileSystemUtils.directoryExists(changeDir)) {
+        throw new Error(`变更「${folderName}」已经存在：${changeDir}`);
+    }
+    // Write a project config only when none exists. The config records the
+    // project default schema, never a one-change --schema override.
+    const freespecDir = path.join(projectRoot, 'freespec');
+    // Create the directory (including parent directories if needed)
+    await FileSystemUtils.createDirectory(changeDir);
+    const configPath = path.join(freespecDir, 'config.yaml');
+    const configYmlPath = path.join(freespecDir, 'config.yml');
+    if (!(await FileSystemUtils.fileExists(configPath)) &&
+        !(await FileSystemUtils.fileExists(configYmlPath))) {
+        await FileSystemUtils.writeFile(configPath, `schema: ${defaultSchema}\n`);
+    }
+    // Write metadata file with schema and creation date
+    writeChangeMetadata(changeDir, {
+        schema: schemaName,
+        created: formatLocalDate(),
+        ...options.metadata,
+    }, projectRoot);
+    return { schema: schemaName, changeName: folderName, changeDir };
+}
+//# sourceMappingURL=change-utils.js.map

package/dist/utils/ci.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CI environment detection shared by telemetry and the version check.
+ *
+ * Providers set CI to "true", "1", "yes", etc. Only an explicit off-value
+ * counts as "not CI", so an unknown value still suppresses outbound requests
+ * rather than surprising a build.
+ */
+/**
+ * True when `CI` is set to anything other than an explicit off-value.
+ */
+export declare function isCiEnvironment(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=ci.d.ts.map

package/dist/utils/ci.js

@@ -0,0 +1,16 @@
+/**
+ * CI environment detection shared by telemetry and the version check.
+ *
+ * Providers set CI to "true", "1", "yes", etc. Only an explicit off-value
+ * counts as "not CI", so an unknown value still suppresses outbound requests
+ * rather than surprising a build.
+ */
+const CI_DISABLED_VALUES = new Set(['', 'false', '0', 'no', 'off']);
+/**
+ * True when `CI` is set to anything other than an explicit off-value.
+ */
+export function isCiEnvironment(env = process.env) {
+    const value = env.CI;
+    return value !== undefined && !CI_DISABLED_VALUES.has(value.trim().toLowerCase());
+}
+//# sourceMappingURL=ci.js.map