@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/artifact-graph/resolver.d.ts

@@ -0,0 +1,89 @@
+import * as fs from 'node:fs';
+import type { SchemaYaml } from './types.js';
+/**
+ * Error thrown when loading a schema fails.
+ */
+export declare class SchemaLoadError extends Error {
+    readonly schemaPath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, schemaPath: string, cause?: Error | undefined);
+}
+/**
+ * Points the built-in schemas at another directory. The standalone binary has
+ * no package directory on disk, so it passes a function that extracts its
+ * embedded schemas; it runs only when a command first needs them.
+ */
+export declare function setPackageSchemasDir(resolveDir: () => string): void;
+/**
+ * Gets the package's built-in schemas directory path.
+ * Uses import.meta.url to resolve relative to the current module.
+ */
+export declare function getPackageSchemasDir(): string;
+/**
+ * Gets the user's schema override directory path.
+ */
+export declare function getUserSchemasDir(): string;
+/**
+ * Gets the project-local schemas directory path.
+ * @param projectRoot - The project root directory
+ * @returns The path to the project's schemas directory
+ */
+export declare function getProjectSchemasDir(projectRoot: string): string;
+export declare function isSchemaDir(parentDir: string, entry: fs.Dirent): boolean;
+/**
+ * Resolves a schema name to its directory path.
+ *
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/freespec/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/freespec/schemas/<name>/schema.yaml
+ * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * When projectRoot is not provided, only user override and package built-in are checked
+ * (backward compatible behavior).
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @param projectRoot - Optional project root directory for project-local schema resolution
+ * @returns The path to the schema directory, or null if not found
+ */
+export declare function getSchemaDir(name: string, projectRoot?: string): string | null;
+/**
+ * Resolves a schema name to a SchemaYaml object.
+ *
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/freespec/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/freespec/schemas/<name>/schema.yaml
+ * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * When projectRoot is not provided, only user override and package built-in are checked
+ * (backward compatible behavior).
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @param projectRoot - Optional project root directory for project-local schema resolution
+ * @returns The resolved schema object
+ * @throws Error if schema is not found in any location
+ */
+export declare function resolveSchema(name: string, projectRoot?: string): SchemaYaml;
+/**
+ * Lists all available schema names.
+ * Combines project-local, user override, and package built-in schemas.
+ *
+ * @param projectRoot - Optional project root directory for project-local schema resolution
+ */
+export declare function listSchemas(projectRoot?: string): string[];
+/**
+ * Schema info with metadata (name, description, artifacts).
+ */
+export interface SchemaInfo {
+    name: string;
+    description: string;
+    artifacts: string[];
+    source: 'project' | 'user' | 'package';
+}
+/**
+ * Lists all available schemas with their descriptions and artifact lists.
+ * Useful for agent skills to present schema selection to users.
+ *
+ * @param projectRoot - Optional project root directory for project-local schema resolution
+ */
+export declare function listSchemasWithInfo(projectRoot?: string): SchemaInfo[];
+//# sourceMappingURL=resolver.d.ts.map

package/dist/core/artifact-graph/resolver.js

@@ -0,0 +1,342 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getGlobalDataDir } from '../global-config.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { parseSchema, SchemaValidationError } from './schema.js';
+/**
+ * Error thrown when loading a schema fails.
+ */
+export class SchemaLoadError extends Error {
+    schemaPath;
+    cause;
+    constructor(message, schemaPath, cause) {
+        super(message);
+        this.schemaPath = schemaPath;
+        this.cause = cause;
+        this.name = 'SchemaLoadError';
+    }
+}
+let packageSchemasDirOverride;
+/**
+ * Points the built-in schemas at another directory. The standalone binary has
+ * no package directory on disk, so it passes a function that extracts its
+ * embedded schemas; it runs only when a command first needs them.
+ */
+export function setPackageSchemasDir(resolveDir) {
+    packageSchemasDirOverride = resolveDir;
+}
+/**
+ * Gets the package's built-in schemas directory path.
+ * Uses import.meta.url to resolve relative to the current module.
+ */
+export function getPackageSchemasDir() {
+    if (packageSchemasDirOverride)
+        return packageSchemasDirOverride();
+    const currentFile = fileURLToPath(import.meta.url);
+    // Navigate from dist/core/artifact-graph/ to package root's schemas/
+    return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
+}
+/**
+ * Gets the user's schema override directory path.
+ */
+export function getUserSchemasDir() {
+    return path.join(getGlobalDataDir(), 'schemas');
+}
+/**
+ * Gets the project-local schemas directory path.
+ * @param projectRoot - The project root directory
+ * @returns The path to the project's schemas directory
+ */
+export function getProjectSchemasDir(projectRoot) {
+    return path.join(projectRoot, 'freespec', 'schemas');
+}
+/**
+ * Determines whether a directory entry represents a schema directory candidate.
+ *
+ * Returns true for real directories and for symlinks whose target is a
+ * directory. `fs.Dirent.isDirectory()` reports the raw entry type, so a symlink
+ * (even one pointing at a directory) has `isDirectory() === false`; we
+ * dereference such entries via `fs.statSync` to admit symlinked schema dirs
+ * while still rejecting symlinks-to-files and broken/dangling symlinks.
+ *
+ * @param parentDir - The directory containing the entry
+ * @param entry - The directory entry from `fs.readdirSync(..., { withFileTypes: true })`
+ */
+/**
+ * Directories `schema fork` and `schema init` create transiently while swapping
+ * a schema into place: a staging copy (`.fork-staging-<rand>` /
+ * `.init-staging-<rand>`, created via mkdtemp) and a backup of the previous
+ * destination (`<name>.fork-backup-<pid>-<ts>` /
+ * `<name>.init-backup-<pid>-<ts>`). Either can briefly coexist with real
+ * schemas in the schemas dir, and a backup outlives the run when its cleanup is
+ * blocked, so discovery must never surface them. Real schema names are
+ * kebab-case (no dots), so excluding these dot-bearing temp names can never
+ * hide a legitimate schema.
+ */
+function isOwnedTransientSchemaDir(name) {
+    return (name.startsWith('.fork-staging-') ||
+        name.includes('.fork-backup-') ||
+        name.startsWith('.init-staging-') ||
+        name.includes('.init-backup-'));
+}
+export function isSchemaDir(parentDir, entry) {
+    if (isOwnedTransientSchemaDir(entry.name)) {
+        return false;
+    }
+    if (entry.isDirectory()) {
+        return true;
+    }
+    if (entry.isSymbolicLink()) {
+        try {
+            // statSync follows the link; isDirectory() reflects the target type.
+            return fs.statSync(path.join(parentDir, entry.name)).isDirectory();
+        }
+        catch {
+            // Broken symlink (dangling target) — statSync throws; treat as non-dir.
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Returns a schema directory only when its schema file stays within that
+ * directory's canonical trust boundary. The directory itself may be a symlink;
+ * external user schema links are an intentionally supported workflow.
+ */
+function getSchemaCandidateDir(schemasDir, name) {
+    const schemaDir = path.join(schemasDir, name);
+    const schemaPath = path.join(schemaDir, 'schema.yaml');
+    if (!fs.existsSync(schemaPath)) {
+        return null;
+    }
+    try {
+        FileSystemUtils.assertPathWithin(schemaDir, schemaPath);
+        return schemaDir;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves a schema name to its directory path.
+ *
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/freespec/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/freespec/schemas/<name>/schema.yaml
+ * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * When projectRoot is not provided, only user override and package built-in are checked
+ * (backward compatible behavior).
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @param projectRoot - Optional project root directory for project-local schema resolution
+ * @returns The path to the schema directory, or null if not found
+ */
+export function getSchemaDir(name, projectRoot) {
+    if (name.length === 0 ||
+        name === '.' ||
+        name === '..' ||
+        /[\\/]/u.test(name) ||
+        /^[A-Za-z]:/u.test(name) ||
+        path.posix.isAbsolute(name) ||
+        path.win32.isAbsolute(name)) {
+        return null;
+    }
+    // 1. Check project-local directory (if projectRoot provided)
+    if (projectRoot) {
+        const projectDir = getSchemaCandidateDir(getProjectSchemasDir(projectRoot), name);
+        if (projectDir) {
+            return projectDir;
+        }
+    }
+    // 2. Check user override directory
+    const userDir = getSchemaCandidateDir(getUserSchemasDir(), name);
+    if (userDir) {
+        return userDir;
+    }
+    // 3. Check package built-in directory
+    const packageDir = getSchemaCandidateDir(getPackageSchemasDir(), name);
+    if (packageDir) {
+        return packageDir;
+    }
+    return null;
+}
+/**
+ * Resolves a schema name to a SchemaYaml object.
+ *
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/freespec/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/freespec/schemas/<name>/schema.yaml
+ * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * When projectRoot is not provided, only user override and package built-in are checked
+ * (backward compatible behavior).
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @param projectRoot - Optional project root directory for project-local schema resolution
+ * @returns The resolved schema object
+ * @throws Error if schema is not found in any location
+ */
+export function resolveSchema(name, projectRoot) {
+    // Normalize name (remove .yaml extension if provided)
+    const normalizedName = name.replace(/\.ya?ml$/, '');
+    const schemaDir = getSchemaDir(normalizedName, projectRoot);
+    if (!schemaDir) {
+        const availableSchemas = listSchemas(projectRoot);
+        throw new Error(`Schema '${normalizedName}' not found. Available schemas: ${availableSchemas.join(', ')}`);
+    }
+    const schemaPath = path.join(schemaDir, 'schema.yaml');
+    // Load and parse the schema
+    let content;
+    try {
+        content = fs.readFileSync(schemaPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new SchemaLoadError(`Failed to read schema at '${schemaPath}': ${ioError.message}`, schemaPath, ioError);
+    }
+    try {
+        return parseSchema(content);
+    }
+    catch (err) {
+        if (err instanceof SchemaValidationError) {
+            throw new SchemaLoadError(`Invalid schema at '${schemaPath}': ${err.message}`, schemaPath, err);
+        }
+        const parseError = err instanceof Error ? err : new Error(String(err));
+        throw new SchemaLoadError(`Failed to parse schema at '${schemaPath}': ${parseError.message}`, schemaPath, parseError);
+    }
+}
+/**
+ * Lists all available schema names.
+ * Combines project-local, user override, and package built-in schemas.
+ *
+ * @param projectRoot - Optional project root directory for project-local schema resolution
+ */
+export function listSchemas(projectRoot) {
+    const schemas = new Set();
+    // Add package built-in schemas
+    const packageDir = getPackageSchemasDir();
+    if (fs.existsSync(packageDir)) {
+        for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
+            if (isSchemaDir(packageDir, entry)) {
+                const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    schemas.add(entry.name);
+                }
+            }
+        }
+    }
+    // Add user override schemas (may override package schemas)
+    const userDir = getUserSchemasDir();
+    if (fs.existsSync(userDir)) {
+        for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
+            if (isSchemaDir(userDir, entry)) {
+                const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    schemas.add(entry.name);
+                }
+            }
+        }
+    }
+    // Add project-local schemas (if projectRoot provided)
+    if (projectRoot) {
+        const projectDir = getProjectSchemasDir(projectRoot);
+        if (fs.existsSync(projectDir)) {
+            for (const entry of fs.readdirSync(projectDir, { withFileTypes: true })) {
+                if (isSchemaDir(projectDir, entry)) {
+                    const schemaPath = path.join(projectDir, entry.name, 'schema.yaml');
+                    if (fs.existsSync(schemaPath)) {
+                        schemas.add(entry.name);
+                    }
+                }
+            }
+        }
+    }
+    return Array.from(schemas).sort();
+}
+/**
+ * Lists all available schemas with their descriptions and artifact lists.
+ * Useful for agent skills to present schema selection to users.
+ *
+ * @param projectRoot - Optional project root directory for project-local schema resolution
+ */
+export function listSchemasWithInfo(projectRoot) {
+    const schemas = [];
+    const seenNames = new Set();
+    // Add project-local schemas first (highest priority, if projectRoot provided)
+    if (projectRoot) {
+        const projectDir = getProjectSchemasDir(projectRoot);
+        if (fs.existsSync(projectDir)) {
+            for (const entry of fs.readdirSync(projectDir, { withFileTypes: true })) {
+                if (isSchemaDir(projectDir, entry)) {
+                    const schemaPath = path.join(projectDir, entry.name, 'schema.yaml');
+                    if (fs.existsSync(schemaPath)) {
+                        try {
+                            const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
+                            schemas.push({
+                                name: entry.name,
+                                description: schema.description || '',
+                                artifacts: schema.artifacts.map((a) => a.id),
+                                source: 'project',
+                            });
+                            seenNames.add(entry.name);
+                        }
+                        catch {
+                            // Skip invalid schemas
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Add user override schemas (if not overridden by project)
+    const userDir = getUserSchemasDir();
+    if (fs.existsSync(userDir)) {
+        for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
+            if (isSchemaDir(userDir, entry) && !seenNames.has(entry.name)) {
+                const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    try {
+                        const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
+                        schemas.push({
+                            name: entry.name,
+                            description: schema.description || '',
+                            artifacts: schema.artifacts.map((a) => a.id),
+                            source: 'user',
+                        });
+                        seenNames.add(entry.name);
+                    }
+                    catch {
+                        // Skip invalid schemas
+                    }
+                }
+            }
+        }
+    }
+    // Add package built-in schemas (if not overridden by project or user)
+    const packageDir = getPackageSchemasDir();
+    if (fs.existsSync(packageDir)) {
+        for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
+            if (isSchemaDir(packageDir, entry) && !seenNames.has(entry.name)) {
+                const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    try {
+                        const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
+                        schemas.push({
+                            name: entry.name,
+                            description: schema.description || '',
+                            artifacts: schema.artifacts.map((a) => a.id),
+                            source: 'package',
+                        });
+                    }
+                    catch {
+                        // Skip invalid schemas
+                    }
+                }
+            }
+        }
+    }
+    return schemas.sort((a, b) => a.name.localeCompare(b.name));
+}
+//# sourceMappingURL=resolver.js.map

package/dist/core/artifact-graph/schema.d.ts

@@ -0,0 +1,27 @@
+import { type SchemaYaml } from './types.js';
+export declare class SchemaValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Loads and validates an artifact schema from a YAML file.
+ */
+export declare function loadSchema(filePath: string): SchemaYaml;
+/**
+ * Parses and validates an artifact schema from YAML content.
+ */
+export declare function parseSchema(yamlContent: string): SchemaYaml;
+/**
+ * Describes an `apply.tracks` value that is not exactly equal to any artifact's
+ * `generates` value, or returns undefined when there is nothing to report.
+ *
+ * The tracked-tasks lookups select the artifact whose `generates` string equals
+ * `tracks`, so this is a progress-discovery problem, not a claim that nothing
+ * produces the file: a glob `generates: tasks/*.md` really does generate
+ * `tracks: tasks/main.md`, yet the strings differ, so the lookup still misses.
+ * Either way apply keeps working (it reads the path directly), but `freespec
+ * list` and `freespec status` fall back to counting the top-level `tasks.md`,
+ * and apply's remedy cannot name an artifact to build. A typo such as
+ * `task.md` is the other usual cause.
+ */
+export declare function findApplyTracksWarning(schema: SchemaYaml): string | undefined;
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/artifact-graph/schema.js

@@ -0,0 +1,160 @@
+import * as fs from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { SchemaYamlSchema } from './types.js';
+export class SchemaValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SchemaValidationError';
+    }
+}
+/**
+ * Loads and validates an artifact schema from a YAML file.
+ */
+export function loadSchema(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseSchema(content);
+}
+/**
+ * Parses and validates an artifact schema from YAML content.
+ */
+export function parseSchema(yamlContent) {
+    const parsed = parseYaml(yamlContent);
+    // Validate with Zod
+    const result = SchemaYamlSchema.safeParse(parsed);
+    if (!result.success) {
+        const errors = result.error.issues.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
+        throw new SchemaValidationError(`Invalid schema: ${errors}`);
+    }
+    const schema = result.data;
+    // Check for duplicate artifact IDs
+    validateNoDuplicateIds(schema.artifacts);
+    // Check that all requires references are valid
+    validateRequiresReferences(schema.artifacts);
+    // Check that the apply phase names artifacts this schema declares
+    validateApplyReferences(schema);
+    // Check for cycles
+    validateNoCycles(schema.artifacts);
+    return schema;
+}
+/**
+ * Validates that there are no duplicate artifact IDs.
+ */
+function validateNoDuplicateIds(artifacts) {
+    const seen = new Set();
+    for (const artifact of artifacts) {
+        if (seen.has(artifact.id)) {
+            throw new SchemaValidationError(`Duplicate artifact ID: ${artifact.id}`);
+        }
+        seen.add(artifact.id);
+    }
+}
+/**
+ * Validates that all `requires` references point to valid artifact IDs.
+ */
+function validateRequiresReferences(artifacts) {
+    const validIds = new Set(artifacts.map(a => a.id));
+    for (const artifact of artifacts) {
+        for (const req of artifact.requires) {
+            if (!validIds.has(req)) {
+                throw new SchemaValidationError(`Invalid dependency reference in artifact '${artifact.id}': '${req}' does not exist`);
+            }
+        }
+    }
+}
+/**
+ * Validates that every `apply.requires` id is an artifact the schema declares.
+ *
+ * Apply skips an id that no artifact declares, so a typo silently dropped that
+ * artifact from the apply gate. An unknown artifact `requires` is already a
+ * load error, and this is the same kind of reference.
+ *
+ * `apply.tracks` is deliberately not checked here. It is a path, not an id:
+ * apply reads it as written, so a schema whose `tracks` value does not exactly
+ * match any `generates` value (a hand-written `TODO.md`, or `tasks/main.md`
+ * under a glob `generates: tasks/*.md` that really does produce it) works
+ * today, and failing the load would break every command on it.
+ * `freespec schema validate` reports that case as a warning instead
+ * (see `findApplyTracksWarning`).
+ */
+function validateApplyReferences(schema) {
+    const apply = schema.apply;
+    if (!apply)
+        return;
+    const validIds = schema.artifacts.map(a => a.id);
+    for (const req of apply.requires) {
+        if (!validIds.includes(req)) {
+            throw new SchemaValidationError(`Invalid apply.requires reference: '${req}' does not exist (artifacts: ${validIds.join(', ')})`);
+        }
+    }
+}
+/**
+ * Describes an `apply.tracks` value that is not exactly equal to any artifact's
+ * `generates` value, or returns undefined when there is nothing to report.
+ *
+ * The tracked-tasks lookups select the artifact whose `generates` string equals
+ * `tracks`, so this is a progress-discovery problem, not a claim that nothing
+ * produces the file: a glob `generates: tasks/*.md` really does generate
+ * `tracks: tasks/main.md`, yet the strings differ, so the lookup still misses.
+ * Either way apply keeps working (it reads the path directly), but `freespec
+ * list` and `freespec status` fall back to counting the top-level `tasks.md`,
+ * and apply's remedy cannot name an artifact to build. A typo such as
+ * `task.md` is the other usual cause.
+ */
+export function findApplyTracksWarning(schema) {
+    const tracks = schema.apply?.tracks;
+    if (tracks == null || schema.artifacts.some(a => a.generates === tracks))
+        return undefined;
+    return (`apply.tracks '${tracks}' does not exactly match any artifact's generates value ` +
+        `(generates: ${schema.artifacts.map(a => a.generates).join(', ')}), ` +
+        `so FreeSpec cannot tell which artifact's progress it tracks. ` +
+        `Apply still reads that file as written, but list and status count tasks.md instead. ` +
+        `Make apply.tracks exactly equal one of those generates values, ` +
+        `or confirm that file is maintained outside the artifact graph.`);
+}
+/**
+ * Validates that there are no cyclic dependencies.
+ * Uses DFS to detect cycles and reports the full cycle path.
+ */
+function validateNoCycles(artifacts) {
+    const artifactMap = new Map(artifacts.map(a => [a.id, a]));
+    const visited = new Set();
+    const inStack = new Set();
+    const parent = new Map();
+    function dfs(id) {
+        visited.add(id);
+        inStack.add(id);
+        const artifact = artifactMap.get(id);
+        if (!artifact)
+            return null;
+        for (const dep of artifact.requires) {
+            if (!visited.has(dep)) {
+                parent.set(dep, id);
+                const cycle = dfs(dep);
+                if (cycle)
+                    return cycle;
+            }
+            else if (inStack.has(dep)) {
+                // Found a cycle - reconstruct the path
+                const cyclePath = [dep];
+                let current = id;
+                while (current !== dep) {
+                    cyclePath.unshift(current);
+                    current = parent.get(current);
+                }
+                cyclePath.unshift(dep);
+                return cyclePath.join(' → ');
+            }
+        }
+        inStack.delete(id);
+        return null;
+    }
+    for (const artifact of artifacts) {
+        if (!visited.has(artifact.id)) {
+            const cycle = dfs(artifact.id);
+            if (cycle) {
+                throw new SchemaValidationError(`Cyclic dependency detected: ${cycle}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/artifact-graph/state.d.ts

@@ -0,0 +1,12 @@
+import type { CompletedSet } from './types.js';
+import type { ArtifactGraph } from './graph.js';
+/**
+ * Detects which artifacts are completed by checking file existence in the change directory.
+ * Returns a Set of completed artifact IDs.
+ *
+ * @param graph - The artifact graph to check
+ * @param changeDir - The change directory to scan for files
+ * @returns Set of artifact IDs whose generated files exist
+ */
+export declare function detectCompleted(graph: ArtifactGraph, changeDir: string): CompletedSet;
+//# sourceMappingURL=state.d.ts.map

package/dist/core/artifact-graph/state.js

@@ -0,0 +1,31 @@
+import * as fs from 'node:fs';
+import { artifactOutputExists } from './outputs.js';
+/**
+ * Detects which artifacts are completed by checking file existence in the change directory.
+ * Returns a Set of completed artifact IDs.
+ *
+ * @param graph - The artifact graph to check
+ * @param changeDir - The change directory to scan for files
+ * @returns Set of artifact IDs whose generated files exist
+ */
+export function detectCompleted(graph, changeDir) {
+    const completed = new Set();
+    // Handle missing change directory gracefully
+    if (!fs.existsSync(changeDir)) {
+        return completed;
+    }
+    for (const artifact of graph.getAllArtifacts()) {
+        if (isArtifactComplete(artifact.generates, changeDir)) {
+            completed.add(artifact.id);
+        }
+    }
+    return completed;
+}
+/**
+ * Checks if an artifact is complete by checking if its generated file(s) exist.
+ * Supports both simple paths and glob patterns.
+ */
+function isArtifactComplete(generates, changeDir) {
+    return artifactOutputExists(changeDir, generates);
+}
+//# sourceMappingURL=state.js.map