@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/commands/workflow/new-change.js

@@ -0,0 +1,135 @@
+/**
+ * New Change Command
+ *
+ * Creates a new change directory with optional description and schema in the
+ * resolved FreeSpec root. Initiative linking and workspace affected areas
+ * are no longer part of this command.
+ */
+import chalk from 'chalk';
+import path from 'path';
+import { createChange, validateChangeName } from '../../utils/change-utils.js';
+import { normalizeChangeName } from '../../core/change-layout.js';
+import { formatChangeLocation } from '../../core/planning-home.js';
+import { resolveRootForCommand, RootSelectionError, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
+import { readProjectConfig } from '../../core/project-config.js';
+import { printJson, statusFromError, validateSchemaExists } from './shared.js';
+// -----------------------------------------------------------------------------
+// Command Implementation
+// -----------------------------------------------------------------------------
+function assertRemovedOptionsAbsent(options) {
+    if (options.initiative !== undefined) {
+        throw new RootSelectionError('--initiative is no longer supported. Normal changes no longer attach to initiatives; --store <id> selects the FreeSpec root.', 'initiative_option_removed', { target: 'change.options' });
+    }
+    if (options.areas !== undefined) {
+        throw new RootSelectionError('--areas is no longer supported. Workspace affected areas are not part of the normal FreeSpec root path.', 'areas_option_removed', { target: 'change.options' });
+    }
+}
+function printCreatedChangeHuman(payload, root) {
+    // A relative path is only honest when the root is where the user
+    // stands; a distant ancestor root gets the absolute path.
+    const location = root.path === process.cwd()
+        ? formatChangeLocation(toPlanningHome(root), payload.change.id)
+        : payload.change.path;
+    console.log(`Created change '${payload.change.id}' at ${location}/`);
+    console.log(`Schema: ${payload.change.schema}`);
+    console.log(`Next: freespec status --change ${payload.change.id}`);
+}
+/**
+ * An implicit root is the fallback taken when no `freespec/` directory was
+ * found: creating a change there materializes FreeSpec in whatever directory
+ * the caller happened to be in, which is how an agent ends up adopting a
+ * project that never ran `freespec init` (#1645). The creation itself stays
+ * zero-config; this only makes it visible.
+ */
+function printImplicitRootNotice(root) {
+    if (root.source !== 'implicit') {
+        return;
+    }
+    const freespecDir = path.dirname(root.changesDir);
+    const relative = path.relative(process.cwd(), freespecDir);
+    const location = relative && !relative.startsWith('..') ? relative : freespecDir;
+    console.log();
+    console.log(chalk.dim(`Note: no FreeSpec root was found here, so one was created at ${location}/.`));
+    console.log(chalk.dim('Run `freespec init` to finish setting this project up, or delete that directory if you meant a different project.'));
+}
+export async function newChangeCommand(name, options) {
+    let spinner;
+    if (!options.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora();
+    }
+    try {
+        if (!name) {
+            throw new Error('Missing required argument <name>');
+        }
+        const folderName = normalizeChangeName(name);
+        const validation = validateChangeName(folderName);
+        if (!validation.valid) {
+            throw new Error(validation.error);
+        }
+        assertRemovedOptionsAbsent(options);
+        const root = await resolveRootForCommand(options, {
+            json: options.json,
+            failurePayload: { change: null },
+        });
+        if (!root) {
+            return;
+        }
+        const projectRoot = root.path;
+        // Validate schema if provided
+        if (options.schema) {
+            validateSchemaExists(options.schema, projectRoot);
+        }
+        // Resolve the schema once (--schema, then config, then the root default)
+        // and hand it to createChange, so the progress line names the schema the
+        // change gets and config warnings print only once. An empty --schema is
+        // absent, matching createChange's `if (options.schema)`.
+        const resolvedSchema = options.schema || (readProjectConfig(projectRoot)?.schema ?? root.defaultSchema);
+        if (spinner) {
+            spinner.start(`正在创建「${folderName}」，schema「${resolvedSchema}」...`);
+        }
+        const result = await createChange(projectRoot, folderName, {
+            schema: resolvedSchema,
+            defaultSchema: root.defaultSchema,
+            changesDir: root.changesDir,
+            metadata: {
+                ...(options.goal ? { goal: options.goal } : {}),
+            },
+        });
+        // If description provided, create README.md with description
+        if (options.description) {
+            const { promises: fs } = await import('fs');
+            const readmePath = path.join(result.changeDir, 'README.md');
+            await fs.writeFile(readmePath, `# ${name}\n\n${options.description}\n`, 'utf-8');
+        }
+        const payload = {
+            change: {
+                id: result.changeName,
+                path: result.changeDir,
+                metadataPath: path.join(result.changeDir, '.freespec.yaml'),
+                schema: result.schema,
+            },
+            root: toRootOutput(root),
+        };
+        if (options.json) {
+            printJson(payload);
+            return;
+        }
+        spinner?.stop();
+        printCreatedChangeHuman(payload, root);
+        printImplicitRootNotice(root);
+    }
+    catch (error) {
+        spinner?.stop();
+        if (options.json) {
+            printJson({
+                change: null,
+                status: [statusFromError(error)],
+            });
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=new-change.js.map

package/dist/commands/workflow/shared.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared Types and Utilities for Artifact Workflow Commands
+ *
+ * This module contains types, constants, and validation helpers used across
+ * multiple artifact workflow commands.
+ */
+export interface ChangeCommandStatus {
+    severity: 'error' | 'warning';
+    code: string;
+    message: string;
+    target?: string;
+    fix?: string;
+}
+export interface TaskItem {
+    id: string;
+    description: string;
+    done: boolean;
+    sourcePath: string;
+    line: number;
+}
+export interface ApplyInstructions {
+    changeName: string;
+    changeDir: string;
+    schemaName: string;
+    contextFiles: Record<string, string[]>;
+    progress: {
+        total: number;
+        complete: number;
+        remaining: number;
+    };
+    tasks: TaskItem[];
+    taskTrackingConfigured: boolean;
+    unavailableTrackingFiles?: Array<{
+        path: string;
+        reason: string;
+    }>;
+    state: 'blocked' | 'all_done' | 'ready';
+    missingArtifacts?: string[];
+    /**
+     * Everything still to build before apply can run, in build order - the
+     * transitive closure of the schema's `apply.requires`, so it can be longer
+     * than `missingArtifacts`, which stops at the first hop apply blocks on.
+     */
+    missingPrerequisites?: string[];
+    /** Non-blocking problems with the change, reported alongside the instruction. */
+    warnings?: string[];
+    instruction: string;
+    /** Current project background from the selected root. */
+    context?: string;
+    /** Current advisory guidance for apply. */
+    operationGuidance?: string[];
+}
+export interface ArchiveInstructions {
+    changeName: string;
+    /** Current project background from the selected root. */
+    context?: string;
+    /** Current advisory guidance for archive. */
+    operationGuidance?: string[];
+}
+export { DEFAULT_SCHEMA } from './default-schema.js';
+export declare function printJson(payload: unknown): void;
+export declare function statusFromError(error: unknown): ChangeCommandStatus;
+/**
+ * Checks if color output is disabled via NO_COLOR env or --no-color flag.
+ */
+export declare function isColorDisabled(): boolean;
+/**
+ * Gets the color function based on status.
+ */
+export declare function getStatusColor(status: 'done' | 'skipped' | 'ready' | 'blocked'): (text: string) => string;
+/**
+ * Gets the status indicator for an artifact.
+ */
+export declare function getStatusIndicator(status: 'done' | 'skipped' | 'ready' | 'blocked'): string;
+/**
+ * Returns change directory names directly under freespec/.
+ * A change folder is named `<名称>变更`. Hidden directories are excluded.
+ */
+export declare function getAvailableChanges(projectRoot: string, changesDir?: string): Promise<string[]>;
+/**
+ * Validates that a change exists and returns available changes if not.
+ * Checks directory existence directly to support scaffolded changes (without proposal.md).
+ */
+export declare function validateChangeExists(changeName: string | undefined, projectRoot: string, changesDir?: string, hints?: {
+    newChangeHint?: string;
+}): Promise<string>;
+/**
+ * Validates that a schema exists and returns available schemas if not.
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
+ */
+export declare function validateSchemaExists(schemaName: string, projectRoot?: string): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/commands/workflow/shared.js

@@ -0,0 +1,169 @@
+/**
+ * Shared Types and Utilities for Artifact Workflow Commands
+ *
+ * This module contains types, constants, and validation helpers used across
+ * multiple artifact workflow commands.
+ */
+import chalk from 'chalk';
+import path from 'path';
+import { describeNestedChange, findNestedChangesIn, } from '../../utils/nested-change.js';
+import * as fs from 'fs';
+import { getSchemaDir, listSchemas } from '../../core/artifact-graph/index.js';
+import { isRootSelectionError } from '../../core/root-selection.js';
+import { changeParentDir, isChangeDirectoryName } from '../../core/change-layout.js';
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+export { DEFAULT_SCHEMA } from './default-schema.js';
+// -----------------------------------------------------------------------------
+// Utility Functions
+// -----------------------------------------------------------------------------
+export function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+export function statusFromError(error) {
+    if (isRootSelectionError(error)) {
+        return { ...error.diagnostic };
+    }
+    return {
+        severity: 'error',
+        code: 'change_error',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+/**
+ * Checks if color output is disabled via NO_COLOR env or --no-color flag.
+ */
+export function isColorDisabled() {
+    return process.env.NO_COLOR === '1' || process.env.NO_COLOR === 'true';
+}
+/**
+ * Gets the color function based on status.
+ */
+export function getStatusColor(status) {
+    if (isColorDisabled()) {
+        return (text) => text;
+    }
+    switch (status) {
+        case 'done':
+            return chalk.green;
+        case 'skipped':
+            return chalk.gray;
+        case 'ready':
+            return chalk.yellow;
+        case 'blocked':
+            return chalk.red;
+    }
+}
+/**
+ * Gets the status indicator for an artifact.
+ */
+export function getStatusIndicator(status) {
+    const color = getStatusColor(status);
+    switch (status) {
+        case 'done':
+            return color('[x]');
+        case 'skipped':
+            return color('[~]');
+        case 'ready':
+            return color('[ ]');
+        case 'blocked':
+            return color('[-]');
+    }
+}
+/**
+ * Returns change directory names directly under freespec/.
+ * A change folder is named `<名称>变更`. Hidden directories are excluded.
+ */
+export async function getAvailableChanges(projectRoot, changesDir = changeParentDir(projectRoot)) {
+    const changesPath = changesDir;
+    try {
+        const entries = await fs.promises.readdir(changesPath, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() && isChangeDirectoryName(e.name))
+            .map((e) => e.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/**
+ * Validates a change name used to look up an existing change directory.
+ * Lookup accepts any directory name that `getAvailableChanges` could return
+ * (the kebab-case convention in `validateChangeName` applies at creation
+ * time only); it only rejects names that would escape the changes directory
+ * or address entries `getAvailableChanges` excludes (hidden dirs, archive).
+ *
+ * @returns An error message, or undefined if the name is safe to look up
+ */
+function validateChangeLookupName(changeName) {
+    if (changeName === '.' || changeName === '..') {
+        return 'Change name cannot be a relative path segment';
+    }
+    if (changeName.includes('/') || changeName.includes('\\')) {
+        return 'Change name cannot contain path separators';
+    }
+    if (changeName.includes('\0')) {
+        return 'Change name cannot contain null characters';
+    }
+    if (changeName.startsWith('.')) {
+        return 'Change name cannot start with a dot';
+    }
+    return undefined;
+}
+/**
+ * Validates that a change exists and returns available changes if not.
+ * Checks directory existence directly to support scaffolded changes (without proposal.md).
+ */
+export async function validateChangeExists(changeName, projectRoot, changesDir = changeParentDir(projectRoot), hints = {}) {
+    // Hints must stay pasteable: callers with a selected store pass a
+    // store-carrying hint so following it lands in the same root.
+    const newChangeHint = hints.newChangeHint ?? 'freespec new change <name>';
+    if (!changeName) {
+        const available = await getAvailableChanges(projectRoot, changesDir);
+        if (available.length === 0) {
+            throw new Error(`No changes found. Create one with: ${newChangeHint}`);
+        }
+        throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
+    }
+    // Validate change name format to prevent path traversal
+    const lookupError = validateChangeLookupName(changeName);
+    if (lookupError) {
+        throw new Error(`Invalid change name '${changeName}': ${lookupError}`);
+    }
+    // Check directory existence directly
+    const changePath = path.join(changesDir, changeName);
+    const exists = fs.existsSync(changePath) && fs.statSync(changePath).isDirectory();
+    if (!exists) {
+        const available = await getAvailableChanges(projectRoot, changesDir);
+        if (available.length === 0) {
+            throw new Error(`Change '${changeName}' not found. No changes exist. Create one with: ${newChangeHint}`);
+        }
+        throw new Error(`Change '${changeName}' not found. Available changes:\n  ${available.join('\n  ')}`);
+    }
+    // The directory exists but is a namespace folder wrapping nested change
+    // directories. Every artifact lookup below it would report "not started" for
+    // work that is in fact there, so say what is actually wrong instead (#1846).
+    const nested = await findNestedChangesIn(changesDir, changeName);
+    if (nested) {
+        throw new Error(describeNestedChange(nested));
+    }
+    return changeName;
+}
+/**
+ * Validates that a schema exists and returns available schemas if not.
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
+ */
+export function validateSchemaExists(schemaName, projectRoot) {
+    const schemaDir = getSchemaDir(schemaName, projectRoot);
+    if (!schemaDir) {
+        const availableSchemas = listSchemas(projectRoot);
+        throw new Error(`Schema '${schemaName}' not found. Available schemas:\n  ${availableSchemas.join('\n  ')}`);
+    }
+    return schemaName;
+}
+//# sourceMappingURL=shared.js.map

package/dist/commands/workflow/status.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Status Command
+ *
+ * Displays artifact completion status for a change.
+ */
+import { type ChangeStatus } from '../../core/artifact-graph/index.js';
+export interface StatusOptions {
+    change?: string;
+    all?: boolean;
+    schema?: string;
+    store?: string;
+    storePath?: string;
+    json?: boolean;
+}
+export declare const BATCH_STATUS_FAILURE_PAYLOAD: Record<string, unknown>;
+export declare function statusCommand(options: StatusOptions): Promise<void>;
+export declare function printStatusText(status: ChangeStatus): void;
+//# sourceMappingURL=status.d.ts.map

package/dist/commands/workflow/status.js

@@ -0,0 +1,201 @@
+/**
+ * Status Command
+ *
+ * Displays artifact completion status for a change.
+ */
+import chalk from 'chalk';
+import { getChangeDir } from '../../core/planning-home.js';
+import { resolveRootForCommand, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
+import { loadChangeContext, formatChangeStatus, } from '../../core/artifact-graph/index.js';
+import { resolveNextStep } from '../../core/change-status-policy.js';
+import { asStatus } from '../shared-output.js';
+import { describeNestedChange, findNestedChanges, } from '../../utils/nested-change.js';
+import { validateChangeExists, validateSchemaExists, getAvailableChanges, getStatusIndicator, getStatusColor, } from './shared.js';
+// The --all --json failure null-shape. Root-selection failures (handled in
+// resolveRootForCommand) and thrown errors (caught by the CLI wrapper) must
+// emit the same shape, so both call sites reference this one constant.
+export const BATCH_STATUS_FAILURE_PAYLOAD = {
+    changes: [],
+    root: null,
+};
+export async function statusCommand(options) {
+    if (options.all && options.change) {
+        throw new Error('The --all and --change options are mutually exclusive.');
+    }
+    // The root resolves (and the store banner prints) before the spinner starts
+    // so the two do not fight over stderr. The batch null-shape rides along so
+    // a root-selection failure under --all --json still carries `changes: []`.
+    const root = await resolveRootForCommand(options, {
+        json: options.json,
+        failurePayload: options.all ? BATCH_STATUS_FAILURE_PAYLOAD : undefined,
+    });
+    if (!root) {
+        return;
+    }
+    let spinner;
+    if (!options.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora('Loading change status...').start();
+    }
+    try {
+        const planningHome = toPlanningHome(root);
+        const projectRoot = root.path;
+        const rootOutput = toRootOutput(root);
+        const newChangeHint = 'freespec new change <name>';
+        // Single definition of "load one change's status" so the batch and
+        // single-change payloads can never drift apart.
+        const loadStatus = (changeName) => formatChangeStatus(loadChangeContext(projectRoot, changeName, options.schema, {
+            changeDir: getChangeDir(planningHome, changeName),
+            planningHome,
+        }));
+        // Handle no-changes case gracefully — status is informational,
+        // so "no changes" is a valid state, not an error.
+        if (!options.change) {
+            // Validate before the no-changes early return so a bogus --schema
+            // fails the same way whether or not any change exists yet.
+            if (options.all && options.schema) {
+                validateSchemaExists(options.schema, projectRoot);
+            }
+            const available = await getAvailableChanges(projectRoot, root.changesDir);
+            if (available.length === 0) {
+                spinner?.stop();
+                if (options.json) {
+                    console.log(JSON.stringify({ changes: [], message: 'No active changes.', root: rootOutput }, null, 2));
+                    return;
+                }
+                console.log(`No active changes. Create one with: ${newChangeHint}`);
+                return;
+            }
+            if (options.all) {
+                // readdir order is platform-dependent; sort for deterministic output,
+                // with the same comparator validate --all uses so the two batch
+                // commands order a given change set identically.
+                const entries = [];
+                // The sweep reads each directory straight through `loadStatus`, so a
+                // namespace folder wrapping nested changes would report a whole
+                // artifact plan for work that is not there (#1846). It carries the same
+                // per-change diagnostic a malformed change does.
+                const nestedByName = new Map((await findNestedChanges(root.changesDir, available)).map((finding) => [
+                    finding.name,
+                    finding,
+                ]));
+                for (const changeName of available.sort((a, b) => a.localeCompare(b))) {
+                    const nested = nestedByName.get(changeName);
+                    if (nested) {
+                        entries.push({
+                            changeName,
+                            status: [asStatus(new Error(describeNestedChange(nested)), 'change_error')],
+                        });
+                        continue;
+                    }
+                    try {
+                        entries.push(loadStatus(changeName));
+                    }
+                    catch (error) {
+                        // One malformed change must not blank the sweep; carry its
+                        // diagnostic in place and keep going.
+                        entries.push({ changeName, status: [asStatus(error, 'change_error')] });
+                    }
+                }
+                spinner?.stop();
+                const failed = entries.some((entry) => !('artifacts' in entry));
+                if (options.json) {
+                    console.log(JSON.stringify({ changes: entries, root: rootOutput }, null, 2));
+                    if (failed) {
+                        process.exitCode = 1;
+                    }
+                    return;
+                }
+                entries.forEach((entry, index) => {
+                    if (index > 0) {
+                        console.log();
+                    }
+                    if ('artifacts' in entry) {
+                        printStatusText(entry);
+                    }
+                    else {
+                        console.log(chalk.red(`✗ ${entry.changeName}: ${entry.status[0]?.message}`));
+                    }
+                });
+                // A partial load is still a failed command in both output modes;
+                // JSON callers can parse the complete envelope independently of
+                // the process exit code.
+                if (failed) {
+                    process.exitCode = 1;
+                }
+                return;
+            }
+            // Changes exist but neither --change nor --all provided. Name --all
+            // here too: it is the other way to answer this prompt, and a caller
+            // who wants every change should not have to find it in --help.
+            spinner?.stop();
+            throw new Error(`Missing required option --change (or --all for every active change). Available changes:\n  ${available.join('\n  ')}`);
+        }
+        const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint });
+        // Validate schema if explicitly provided
+        if (options.schema) {
+            validateSchemaExists(options.schema, projectRoot);
+        }
+        // loadChangeContext will auto-detect schema from metadata if not provided
+        const status = loadStatus(changeName);
+        spinner?.stop();
+        if (options.json) {
+            console.log(JSON.stringify({ ...status, root: rootOutput }, null, 2));
+            return;
+        }
+        printStatusText(status);
+    }
+    catch (error) {
+        spinner?.stop();
+        throw error;
+    }
+}
+export function printStatusText(status) {
+    const doneCount = status.artifacts.filter((a) => a.status === 'done').length;
+    const skippedCount = status.artifacts.filter((a) => a.status === 'skipped').length;
+    const total = status.artifacts.length - skippedCount;
+    console.log(`Change: ${status.changeName}`);
+    console.log(`Schema: ${status.schemaName}`);
+    if (status.warnings) {
+        for (const warning of status.warnings) {
+            console.log(chalk.yellow(`Warning: ${warning}`));
+        }
+    }
+    if (status.changeRoot) {
+        console.log(`Change root: ${status.changeRoot}`);
+    }
+    const skippedSuffix = skippedCount > 0 ? ` (${skippedCount} skipped)` : '';
+    console.log(`Progress: ${doneCount}/${total} artifacts complete${skippedSuffix}`);
+    console.log();
+    for (const artifact of status.artifacts) {
+        const indicator = getStatusIndicator(artifact.status);
+        const color = getStatusColor(artifact.status);
+        let line = `${indicator} ${artifact.id}`;
+        if (artifact.status === 'skipped') {
+            line += color(' (skipped: change declares skip_specs)');
+        }
+        if (artifact.status === 'blocked' && artifact.missingDeps && artifact.missingDeps.length > 0) {
+            line += color(` (blocked by: ${artifact.missingDeps.join(', ')})`);
+        }
+        console.log(line);
+    }
+    // Derived from the same inputs as the JSON `nextSteps` sentence, so the two
+    // surfaces always name the same command. Without this line the text surface
+    // reports state and no verb, which leaves someone resuming a change - after a
+    // lost session, or on a change they did not start - with nowhere to go.
+    const nextStep = resolveNextStep({
+        changeName: status.changeName,
+        artifactStatuses: status.artifacts,
+        allArtifactsComplete: status.isPlanningComplete,
+    });
+    if (status.isPlanningComplete || nextStep) {
+        console.log();
+    }
+    if (status.isPlanningComplete) {
+        console.log(chalk.green('All planning artifacts complete!'));
+    }
+    if (nextStep) {
+        console.log(`Next: ${nextStep.command}`);
+    }
+}
+//# sourceMappingURL=status.js.map