@seanmars/tospec 0.4.2

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

@@ -0,0 +1,56 @@
+import type { Artifact, SchemaYaml, CompletedSet, BlockedArtifacts } from './types.js';
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ */
+export declare class ArtifactGraph {
+    private artifacts;
+    private schema;
+    private constructor();
+    /**
+     * Creates an ArtifactGraph from a YAML file path.
+     */
+    static fromYaml(filePath: string): ArtifactGraph;
+    /**
+     * Creates an ArtifactGraph from YAML content string.
+     */
+    static fromYamlContent(yamlContent: string): ArtifactGraph;
+    /**
+     * Creates an ArtifactGraph from a pre-validated schema object.
+     */
+    static fromSchema(schema: SchemaYaml): ArtifactGraph;
+    /**
+     * Gets a single artifact by ID.
+     */
+    getArtifact(id: string): Artifact | undefined;
+    /**
+     * Gets all artifacts in the graph.
+     */
+    getAllArtifacts(): Artifact[];
+    /**
+     * Gets the schema name.
+     */
+    getName(): string;
+    /**
+     * Gets the schema version.
+     */
+    getVersion(): number;
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in the order they should be built.
+     */
+    getBuildOrder(): string[];
+    /**
+     * Gets artifacts that are ready to be created (all dependencies completed).
+     */
+    getNextArtifacts(completed: CompletedSet): string[];
+    /**
+     * Checks if all artifacts in the graph are completed.
+     */
+    isComplete(completed: CompletedSet): boolean;
+    /**
+     * Gets blocked artifacts and their unmet dependencies.
+     */
+    getBlocked(completed: CompletedSet): BlockedArtifacts;
+}
+//# sourceMappingURL=graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/core/artifact-graph/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGvF;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,MAAM,CAAa;IAE3B,OAAO;IAKP;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa;IAKhD;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa;IAK1D;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa;IAIpD;;OAEG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI7C;;OAEG;IACH,eAAe,IAAI,QAAQ,EAAE;IAI7B;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;;OAGG;IACH,aAAa,IAAI,MAAM,EAAE;IA2CzB;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,EAAE;IAoBnD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO;IAS5C;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,YAAY,GAAG,gBAAgB;CAkBtD"}

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

@@ -0,0 +1,141 @@
+import { loadSchema, parseSchema } from './schema.js';
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ */
+export class ArtifactGraph {
+    artifacts;
+    schema;
+    constructor(schema) {
+        this.schema = schema;
+        this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));
+    }
+    /**
+     * Creates an ArtifactGraph from a YAML file path.
+     */
+    static fromYaml(filePath) {
+        const schema = loadSchema(filePath);
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Creates an ArtifactGraph from YAML content string.
+     */
+    static fromYamlContent(yamlContent) {
+        const schema = parseSchema(yamlContent);
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Creates an ArtifactGraph from a pre-validated schema object.
+     */
+    static fromSchema(schema) {
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Gets a single artifact by ID.
+     */
+    getArtifact(id) {
+        return this.artifacts.get(id);
+    }
+    /**
+     * Gets all artifacts in the graph.
+     */
+    getAllArtifacts() {
+        return Array.from(this.artifacts.values());
+    }
+    /**
+     * Gets the schema name.
+     */
+    getName() {
+        return this.schema.name;
+    }
+    /**
+     * Gets the schema version.
+     */
+    getVersion() {
+        return this.schema.version;
+    }
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in the order they should be built.
+     */
+    getBuildOrder() {
+        const inDegree = new Map();
+        const dependents = new Map();
+        // Initialize all artifacts
+        for (const artifact of this.artifacts.values()) {
+            inDegree.set(artifact.id, artifact.requires.length);
+            dependents.set(artifact.id, []);
+        }
+        // Build reverse adjacency (who depends on whom)
+        for (const artifact of this.artifacts.values()) {
+            for (const req of artifact.requires) {
+                dependents.get(req).push(artifact.id);
+            }
+        }
+        // Start with roots (in-degree 0), sorted for determinism
+        const queue = [...this.artifacts.keys()]
+            .filter(id => inDegree.get(id) === 0)
+            .sort();
+        const result = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            result.push(current);
+            // Collect newly ready artifacts, then sort before adding
+            const newlyReady = [];
+            for (const dep of dependents.get(current)) {
+                const newDegree = inDegree.get(dep) - 1;
+                inDegree.set(dep, newDegree);
+                if (newDegree === 0) {
+                    newlyReady.push(dep);
+                }
+            }
+            queue.push(...newlyReady.sort());
+        }
+        return result;
+    }
+    /**
+     * Gets artifacts that are ready to be created (all dependencies completed).
+     */
+    getNextArtifacts(completed) {
+        const ready = [];
+        for (const artifact of this.artifacts.values()) {
+            if (completed.has(artifact.id)) {
+                continue; // Already completed
+            }
+            const allDepsCompleted = artifact.requires.every(req => completed.has(req) || this.artifacts.get(req)?.optional === true);
+            if (allDepsCompleted) {
+                ready.push(artifact.id);
+            }
+        }
+        // Sort for deterministic ordering
+        return ready.sort();
+    }
+    /**
+     * Checks if all artifacts in the graph are completed.
+     */
+    isComplete(completed) {
+        for (const artifact of this.artifacts.values()) {
+            if (!artifact.optional && !completed.has(artifact.id)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Gets blocked artifacts and their unmet dependencies.
+     */
+    getBlocked(completed) {
+        const blocked = {};
+        for (const artifact of this.artifacts.values()) {
+            if (completed.has(artifact.id)) {
+                continue; // Already completed
+            }
+            const unmetDeps = artifact.requires.filter(req => !completed.has(req) && this.artifacts.get(req)?.optional !== true);
+            if (unmetDeps.length > 0) {
+                blocked[artifact.id] = unmetDeps.sort();
+            }
+        }
+        return blocked;
+    }
+}
+//# sourceMappingURL=graph.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../../src/core/artifact-graph/graph.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,9 @@
+export { ArtifactSchema, SchemaYamlSchema, type Artifact, type SchemaYaml, type CompletedSet, type BlockedArtifacts, } from './types.js';
+export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
+export { ArtifactGraph } from './graph.js';
+export { detectCompleted } from './state.js';
+export { artifactOutputExists, isGlobPattern, resolveArtifactOutputs } from './outputs.js';
+export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, type SchemaInfo, } from './resolver.js';
+export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, type ChangeContext, type LoadChangeContextOptions, type ArtifactInstructions, type DependencyInfo, type ArtifactStatus, type ChangeStatus, type ArtifactPathSummary, } from './instruction-loader.js';
+export type { PlanningHomeSummary, ActionContext, } from '../change-status-policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/artifact-graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/artifact-graph/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAG3F,OAAO,EACL,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,mBAAmB,EACnB,aAAa,GACd,MAAM,4BAA4B,CAAC"}

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

@@ -0,0 +1,14 @@
+// Types
+export { ArtifactSchema, SchemaYamlSchema, } from './types.js';
+// Schema loading and validation
+export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
+// Graph operations
+export { ArtifactGraph } from './graph.js';
+// State detection
+export { detectCompleted } from './state.js';
+export { artifactOutputExists, isGlobPattern, resolveArtifactOutputs } from './outputs.js';
+// Schema resolution
+export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, } from './resolver.js';
+// Instruction loading
+export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, } from './instruction-loader.js';
+//# sourceMappingURL=index.js.map

package/dist/core/artifact-graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/artifact-graph/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,OAAO,EACL,cAAc,EACd,gBAAgB,GAKjB,MAAM,YAAY,CAAC;AAEpB,gCAAgC;AAChC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE7E,mBAAmB;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,kBAAkB;AAClB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE3F,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAEhB,MAAM,eAAe,CAAC;AAEvB,sBAAsB;AACtB,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAQlB,MAAM,yBAAyB,CAAC"}

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

@@ -0,0 +1,188 @@
+import { ArtifactGraph } from './graph.js';
+import { type ActionContext, type PlanningHomeSummary } from '../change-status-policy.js';
+import { type ProjectConfig } from '../project-config.js';
+import type { ReferenceIndexEntry } from '../references.js';
+import type { PlanningHome } from '../planning-home.js';
+import type { ChangeMetadata } 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;
+}
+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;
+    /** 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;
+    /** Referenced-store index (read-only upstream context; omitted when no references are declared) */
+    references?: ReferenceIndexEntry[];
+    /** 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, blocked, or skipped for an absent optional artifact */
+    status: 'done' | 'ready' | 'blocked' | 'skipped';
+    /** Whether the artifact is optional */
+    optional: boolean;
+    /** Missing dependencies (only for blocked) */
+    missingDeps?: string[];
+}
+/**
+ * Formatted change status.
+ */
+export interface ChangeStatus {
+    /** Change name */
+    changeName: string;
+    /** Schema name */
+    schemaName: string;
+    /** Planning home facts (generated skills derive the archive dir
+     * from planningHome.changesDir - a published agent contract). */
+    planningHome?: PlanningHomeSummary;
+    /** Full path to the change root */
+    changeRoot: string;
+    /** Absolute artifact path details keyed by artifact ID */
+    artifactPaths: Record<string, ArtifactPathSummary>;
+    /** 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., "sdd")
+ * @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 .tospec.yaml metadata (if exists in change directory)
+ * 3. Default 'sdd'
+ *
+ * @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 interface GenerateInstructionsOptions {
+    /** Pre-read project config; suppresses the internal read (no double read). */
+    projectConfig?: ProjectConfig | null;
+    /** Referenced-store index assembled at the command boundary. */
+    references?: ReferenceIndexEntry[];
+}
+export declare function generateInstructions(context: ChangeContext, artifactId: string, projectRoot?: string, options?: GenerateInstructionsOptions): 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-loader.d.ts","sourceRoot":"","sources":["../../../src/core/artifact-graph/instruction-loader.ts"],"names":[],"mappings":"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"}