@thiagodiogo/pastelsdd 1.0.0-beta.1

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -0,0 +1,183 @@
+import { ArtifactGraph } from './graph.js';
+import { type ActionContext, type AffectedAreasSummary, type PlanningHomeSummary } from '../change-status-policy.js';
+import type { PlanningHome } from '../planning-home.js';
+import type { ChangeMetadata, InitiativeLink } from '../change-metadata/index.js';
+import type { CompletedSet } from './types.js';
+/**
+ * Error thrown when loading a template fails.
+ */
+export declare class TemplateLoadError extends Error {
+    readonly templatePath: string;
+    constructor(message: string, templatePath: string);
+}
+/**
+ * Change context containing graph, completion state, and metadata.
+ */
+export interface ChangeContext {
+    /** The artifact dependency graph */
+    graph: ArtifactGraph;
+    /** Set of completed artifact IDs */
+    completed: CompletedSet;
+    /** Schema name being used */
+    schemaName: string;
+    /** Change name */
+    changeName: string;
+    /** Path to the change directory */
+    changeDir: string;
+    /** Project root directory */
+    projectRoot: string;
+    /** Resolved planning home for this change */
+    planningHome?: PlanningHome;
+    /** Parsed change metadata, when present */
+    metadata?: ChangeMetadata;
+    /** Stored initiative link, when this change is linked to shared context */
+    initiative?: InitiativeLink;
+}
+export interface LoadChangeContextOptions {
+    changeDir?: string;
+    planningHome?: PlanningHome;
+}
+/**
+ * Enriched instructions for creating an artifact.
+ */
+export interface ArtifactInstructions {
+    /** Change name */
+    changeName: string;
+    /** Artifact ID */
+    artifactId: string;
+    /** Schema name */
+    schemaName: string;
+    /** Full path to change directory */
+    changeDir: string;
+    /** Resolved planning home for this change */
+    planningHome?: PlanningHomeSummary;
+    /** Stored initiative link, when this change is linked to shared context */
+    initiative?: InitiativeLink;
+    /** Output path pattern (e.g., "proposal.md") */
+    outputPath: string;
+    /** Absolute output path or glob pattern resolved under the change directory */
+    resolvedOutputPath: string;
+    /** Existing concrete output files for this artifact */
+    existingOutputPaths: string[];
+    /** Artifact description */
+    description: string;
+    /** Guidance on how to create this artifact (from schema instruction field) */
+    instruction: string | undefined;
+    /** Project context from config (constraints/background for AI, not to be included in output) */
+    context: string | undefined;
+    /** Artifact-specific rules from config (constraints for AI, not to be included in output) */
+    rules: string[] | undefined;
+    /** Template content (structure to follow - this IS the output format) */
+    template: string;
+    /** Dependencies with completion status and paths */
+    dependencies: DependencyInfo[];
+    /** Artifacts that become available after completing this one */
+    unlocks: string[];
+}
+/**
+ * Dependency information including path and description.
+ */
+export interface DependencyInfo {
+    /** Artifact ID */
+    id: string;
+    /** Whether the dependency is completed */
+    done: boolean;
+    /** Relative output path of the dependency (e.g., "proposal.md") */
+    path: string;
+    /** Description of the dependency artifact */
+    description: string;
+}
+/**
+ * Status of a single artifact in the workflow.
+ */
+export interface ArtifactStatus {
+    /** Artifact ID */
+    id: string;
+    /** Output path pattern */
+    outputPath: string;
+    /** Status: done, ready, or blocked */
+    status: 'done' | 'ready' | 'blocked';
+    /** Missing dependencies (only for blocked) */
+    missingDeps?: string[];
+}
+/**
+ * Formatted change status.
+ */
+export interface ChangeStatus {
+    /** Change name */
+    changeName: string;
+    /** Schema name */
+    schemaName: string;
+    /** Resolved planning home for this change */
+    planningHome?: PlanningHomeSummary;
+    /** Stored initiative link, when this change is linked to shared context */
+    initiative?: InitiativeLink;
+    /** Full path to the change root */
+    changeRoot: string;
+    /** Absolute artifact path details keyed by artifact ID */
+    artifactPaths: Record<string, ArtifactPathSummary>;
+    /** Workspace affected-area summary, when available */
+    affectedAreas?: AffectedAreasSummary;
+    /** Plain-language next steps for users and agents */
+    nextSteps: string[];
+    /** Machine-readable action constraints for agents */
+    actionContext: ActionContext;
+    /** Whether all artifacts are complete */
+    isComplete: boolean;
+    /** Artifact IDs required before apply phase (from schema's apply.requires) */
+    applyRequires: string[];
+    /** Status of each artifact */
+    artifacts: ArtifactStatus[];
+}
+export interface ArtifactPathSummary {
+    outputPath: string;
+    resolvedOutputPath: string;
+    existingOutputPaths: string[];
+}
+/**
+ * Loads a template from a schema's templates directory.
+ *
+ * @param schemaName - Schema name (e.g., "spec-driven")
+ * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The template content
+ * @throws TemplateLoadError if the template cannot be loaded
+ */
+export declare function loadTemplate(schemaName: string, templatePath: string, projectRoot?: string): string;
+/**
+ * Loads change context combining graph and completion state.
+ *
+ * Schema resolution order:
+ * 1. Explicit schemaName parameter (if provided)
+ * 2. Schema from .pastelsdd.yaml metadata (if exists in change directory)
+ * 3. Default 'spec-driven'
+ *
+ * @param projectRoot - Project root directory
+ * @param changeName - Change name
+ * @param schemaName - Optional schema name override. If not provided, auto-detected from metadata.
+ * @returns Change context with graph, completed set, and metadata
+ */
+export declare function loadChangeContext(projectRoot: string, changeName: string, schemaName?: string, options?: LoadChangeContextOptions): ChangeContext;
+/**
+ * Generates enriched instructions for creating an artifact.
+ *
+ * Instruction injection order:
+ * 1. <context> - Project context from config (if present)
+ * 2. <rules> - Artifact-specific rules from config (if present)
+ * 3. <template> - Schema's template content
+ *
+ * @param context - Change context
+ * @param artifactId - Artifact ID to generate instructions for
+ * @param projectRoot - Project root directory (for reading config)
+ * @returns Enriched artifact instructions
+ * @throws Error if artifact not found
+ */
+export declare function generateInstructions(context: ChangeContext, artifactId: string, projectRoot?: string): ArtifactInstructions;
+/**
+ * Formats the status of all artifacts in a change.
+ *
+ * @param context - Change context
+ * @returns Formatted change status
+ */
+export declare function formatChangeStatus(context: ChangeContext): ChangeStatus;
+//# sourceMappingURL=instruction-loader.d.ts.map

package/dist/core/artifact-graph/instruction-loader.js

@@ -0,0 +1,256 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getSchemaDir, resolveSchema } from './resolver.js';
+import { ArtifactGraph } from './graph.js';
+import { detectCompleted } from './state.js';
+import { resolveArtifactOutputs } from './outputs.js';
+import { readChangeMetadata, resolveSchemaForChange } from '../../utils/change-metadata.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { buildActionContext, buildNextSteps, summarizeAffectedAreas, summarizePlanningHome, } from '../change-status-policy.js';
+import { readProjectConfig, validateConfigRules } from '../project-config.js';
+// Session-level cache for validation warnings (avoid repeating same warnings)
+const shownWarnings = new Set();
+/**
+ * Error thrown when loading a template fails.
+ */
+export class TemplateLoadError extends Error {
+    templatePath;
+    constructor(message, templatePath) {
+        super(message);
+        this.templatePath = templatePath;
+        this.name = 'TemplateLoadError';
+    }
+}
+/**
+ * Loads a template from a schema's templates directory.
+ *
+ * @param schemaName - Schema name (e.g., "spec-driven")
+ * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The template content
+ * @throws TemplateLoadError if the template cannot be loaded
+ */
+export function loadTemplate(schemaName, templatePath, projectRoot) {
+    const schemaDir = getSchemaDir(schemaName, projectRoot);
+    if (!schemaDir) {
+        throw new TemplateLoadError(`Schema '${schemaName}' not found`, templatePath);
+    }
+    const templatePathOnDisk = path.join(schemaDir, 'templates', templatePath);
+    if (!fs.existsSync(templatePathOnDisk)) {
+        throw new TemplateLoadError(`Template not found: ${templatePathOnDisk}`, templatePathOnDisk);
+    }
+    const fullPath = FileSystemUtils.canonicalizeExistingPath(templatePathOnDisk);
+    try {
+        return fs.readFileSync(fullPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new TemplateLoadError(`Failed to read template: ${ioError.message}`, fullPath);
+    }
+}
+/**
+ * Loads change context combining graph and completion state.
+ *
+ * Schema resolution order:
+ * 1. Explicit schemaName parameter (if provided)
+ * 2. Schema from .pastelsdd.yaml metadata (if exists in change directory)
+ * 3. Default 'spec-driven'
+ *
+ * @param projectRoot - Project root directory
+ * @param changeName - Change name
+ * @param schemaName - Optional schema name override. If not provided, auto-detected from metadata.
+ * @returns Change context with graph, completed set, and metadata
+ */
+export function loadChangeContext(projectRoot, changeName, schemaName, options = {}) {
+    const changeDir = FileSystemUtils.canonicalizeExistingPath(options.changeDir ?? path.join(projectRoot, 'pastelsdd', 'changes', changeName));
+    const metadata = readChangeMetadata(changeDir, projectRoot) ?? undefined;
+    const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName, projectRoot, {
+        metadata: metadata ?? null,
+    });
+    const schema = resolveSchema(resolvedSchemaName, projectRoot);
+    const graph = ArtifactGraph.fromSchema(schema);
+    const completed = detectCompleted(graph, changeDir);
+    return {
+        graph,
+        completed,
+        schemaName: resolvedSchemaName,
+        changeName,
+        changeDir,
+        projectRoot,
+        ...(options.planningHome ? { planningHome: options.planningHome } : {}),
+        ...(metadata ? { metadata } : {}),
+        ...(metadata?.initiative ? { initiative: metadata.initiative } : {}),
+    };
+}
+/**
+ * Generates enriched instructions for creating an artifact.
+ *
+ * Instruction injection order:
+ * 1. <context> - Project context from config (if present)
+ * 2. <rules> - Artifact-specific rules from config (if present)
+ * 3. <template> - Schema's template content
+ *
+ * @param context - Change context
+ * @param artifactId - Artifact ID to generate instructions for
+ * @param projectRoot - Project root directory (for reading config)
+ * @returns Enriched artifact instructions
+ * @throws Error if artifact not found
+ */
+export function generateInstructions(context, artifactId, projectRoot) {
+    const artifact = context.graph.getArtifact(artifactId);
+    if (!artifact) {
+        throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
+    }
+    const templateContent = loadTemplate(context.schemaName, artifact.template, context.projectRoot);
+    const dependencies = getDependencyInfo(artifact, context.graph, context.completed);
+    const unlocks = getUnlockedArtifacts(context.graph, artifactId);
+    // Use projectRoot from context if not explicitly provided
+    const effectiveProjectRoot = projectRoot ?? context.projectRoot;
+    // Try to read project config for context and rules
+    let projectConfig = null;
+    if (effectiveProjectRoot) {
+        try {
+            projectConfig = readProjectConfig(effectiveProjectRoot);
+        }
+        catch {
+            // If config read fails, continue without config
+        }
+    }
+    // Validate rules artifact IDs if config has rules (only once per session)
+    if (projectConfig?.rules) {
+        const validArtifactIds = new Set(context.graph.getAllArtifacts().map((a) => a.id));
+        const warnings = validateConfigRules(projectConfig.rules, validArtifactIds, context.schemaName);
+        // Show each unique warning only once per session
+        for (const warning of warnings) {
+            if (!shownWarnings.has(warning)) {
+                console.warn(warning);
+                shownWarnings.add(warning);
+            }
+        }
+    }
+    // Extract context and rules as separate fields (not prepended to template)
+    const configContext = projectConfig?.context?.trim() || undefined;
+    const rulesForArtifact = projectConfig?.rules?.[artifactId];
+    const configRules = rulesForArtifact && rulesForArtifact.length > 0 ? rulesForArtifact : undefined;
+    return {
+        changeName: context.changeName,
+        artifactId: artifact.id,
+        schemaName: context.schemaName,
+        changeDir: context.changeDir,
+        planningHome: summarizePlanningHome(context.planningHome),
+        ...(context.initiative ? { initiative: context.initiative } : {}),
+        outputPath: artifact.generates,
+        resolvedOutputPath: path.join(context.changeDir, artifact.generates),
+        existingOutputPaths: resolveArtifactOutputs(context.changeDir, artifact.generates),
+        description: artifact.description,
+        instruction: artifact.instruction,
+        context: configContext,
+        rules: configRules,
+        template: templateContent,
+        dependencies,
+        unlocks,
+    };
+}
+/**
+ * Gets dependency info including paths and descriptions.
+ */
+function getDependencyInfo(artifact, graph, completed) {
+    return artifact.requires.map(id => {
+        const depArtifact = graph.getArtifact(id);
+        return {
+            id,
+            done: completed.has(id),
+            path: depArtifact?.generates ?? id,
+            description: depArtifact?.description ?? '',
+        };
+    });
+}
+/**
+ * Gets artifacts that become available after completing the given artifact.
+ */
+function getUnlockedArtifacts(graph, artifactId) {
+    const unlocks = [];
+    for (const artifact of graph.getAllArtifacts()) {
+        if (artifact.requires.includes(artifactId)) {
+            unlocks.push(artifact.id);
+        }
+    }
+    return unlocks.sort();
+}
+/**
+ * Formats the status of all artifacts in a change.
+ *
+ * @param context - Change context
+ * @returns Formatted change status
+ */
+export function formatChangeStatus(context) {
+    // Load schema to get apply phase configuration
+    const schema = resolveSchema(context.schemaName, context.projectRoot);
+    const applyRequires = schema.apply?.requires ?? schema.artifacts.map(a => a.id);
+    const artifacts = context.graph.getAllArtifacts();
+    const ready = new Set(context.graph.getNextArtifacts(context.completed));
+    const blocked = context.graph.getBlocked(context.completed);
+    const artifactPaths = {};
+    const artifactStatuses = artifacts.map(artifact => {
+        artifactPaths[artifact.id] = {
+            outputPath: artifact.generates,
+            resolvedOutputPath: path.join(context.changeDir, artifact.generates),
+            existingOutputPaths: resolveArtifactOutputs(context.changeDir, artifact.generates),
+        };
+        if (context.completed.has(artifact.id)) {
+            return {
+                id: artifact.id,
+                outputPath: artifact.generates,
+                status: 'done',
+            };
+        }
+        if (ready.has(artifact.id)) {
+            return {
+                id: artifact.id,
+                outputPath: artifact.generates,
+                status: 'ready',
+            };
+        }
+        return {
+            id: artifact.id,
+            outputPath: artifact.generates,
+            status: 'blocked',
+            missingDeps: blocked[artifact.id] ?? [],
+        };
+    });
+    // Sort by build order for consistent output
+    const buildOrder = context.graph.getBuildOrder();
+    const orderMap = new Map(buildOrder.map((id, idx) => [id, idx]));
+    artifactStatuses.sort((a, b) => (orderMap.get(a.id) ?? 0) - (orderMap.get(b.id) ?? 0));
+    const affectedAreas = summarizeAffectedAreas({
+        planningHome: context.planningHome,
+        metadata: context.metadata,
+    });
+    const isComplete = context.graph.isComplete(context.completed);
+    const artifactIds = artifactStatuses.map((artifact) => artifact.id);
+    return {
+        changeName: context.changeName,
+        schemaName: context.schemaName,
+        planningHome: summarizePlanningHome(context.planningHome),
+        ...(context.initiative ? { initiative: context.initiative } : {}),
+        changeRoot: context.changeDir,
+        artifactPaths,
+        affectedAreas,
+        isComplete,
+        applyRequires,
+        nextSteps: buildNextSteps({
+            changeName: context.changeName,
+            planningHome: context.planningHome,
+            artifactStatuses,
+            affectedAreas,
+            allArtifactsComplete: isComplete,
+        }),
+        actionContext: buildActionContext({
+            planningHome: context.planningHome,
+            projectRoot: context.projectRoot,
+            artifactIds,
+        }),
+        artifacts: artifactStatuses,
+    };
+}
+//# sourceMappingURL=instruction-loader.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * Checks if a path contains glob pattern characters.
+ */
+export declare function isGlobPattern(pattern: string): boolean;
+/**
+ * Resolves an artifact's output path(s) to concrete files that currently exist.
+ * Returns absolute file paths. Glob matches are sorted for deterministic output.
+ */
+export declare function resolveArtifactOutputs(changeDir: string, generates: string): string[];
+/**
+ * Checks if an artifact has at least one resolved output file.
+ */
+export declare function artifactOutputExists(changeDir: string, generates: string): boolean;
+//# sourceMappingURL=outputs.d.ts.map

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

@@ -0,0 +1,39 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import { FileSystemUtils } from '../../utils/file-system.js';
+/**
+ * Checks if a path contains glob pattern characters.
+ */
+export function isGlobPattern(pattern) {
+    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
+}
+/**
+ * Resolves an artifact's output path(s) to concrete files that currently exist.
+ * Returns absolute file paths. Glob matches are sorted for deterministic output.
+ */
+export function resolveArtifactOutputs(changeDir, generates) {
+    if (!isGlobPattern(generates)) {
+        const fullPath = path.join(changeDir, generates);
+        try {
+            return fs.statSync(fullPath).isFile()
+                ? [FileSystemUtils.canonicalizeExistingPath(fullPath)]
+                : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    const normalizedPattern = FileSystemUtils.toPosixPath(generates);
+    const matches = fg
+        .sync(normalizedPattern, { cwd: changeDir, onlyFiles: true, absolute: true })
+        .map((match) => FileSystemUtils.canonicalizeExistingPath(path.normalize(match)));
+    return Array.from(new Set(matches)).sort();
+}
+/**
+ * Checks if an artifact has at least one resolved output file.
+ */
+export function artifactOutputExists(changeDir, generates) {
+    return resolveArtifactOutputs(changeDir, generates).length > 0;
+}
+//# sourceMappingURL=outputs.js.map

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

@@ -0,0 +1,81 @@
+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);
+}
+/**
+ * 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;
+/**
+ * Resolves a schema name to its directory path.
+ *
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/pastelsdd/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/pastelsdd/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>/pastelsdd/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/pastelsdd/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