fix: canonicalize workflow artifact paths

[TabishB]

Summary

• canonicalize artifact output paths before returning them in workflow JSON/text outputs
• normalize adjacent existing-file workflow paths (changeDir and template paths) to avoid OS-specific aliases leaking into machine-readable output
• add regression coverage for aliased change directories so Windows-style path aliasing is caught cross-platform

Testing

• pnpm run build
• pnpm test

Summary by CodeRabbit

• Bug Fixes
  • Improved filesystem path canonicalization for more consistent artifact and template resolution
  • Added support for symlinked directories in project structures
  • Enhanced change directory detection with context-aware path resolution for better reliability

[1code-async]

Task completed.

I'll review this PR by examining the changes in detail. Let me start by understanding the codebase context and the specific changes made.

---

View full conversation

Powered by 1Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e59330f5-f5e2-4a32-b59c-0318d3b01fbe

📥 Commits

Reviewing files that changed from the base of the PR and between c0f2904 and 8945ed2.

📒 Files selected for processing (6)

• src/commands/workflow/instructions.ts
• src/commands/workflow/templates.ts
• src/core/artifact-graph/instruction-loader.ts
• src/core/artifact-graph/outputs.ts
• src/utils/file-system.ts
• test/core/artifact-graph/outputs.test.ts

---

📝 Walkthrough

Walkthrough

This PR introduces path canonicalization across the artifact graph system. A new FileSystemUtils.canonicalizeExistingPath() method is added and integrated into template loading, change context resolution, artifact output resolution, and related command handlers to normalize filesystem paths to their canonical forms.

Changes

Cohort / File(s)	Summary
Path Canonicalization Utility src/utils/file-system.ts	Added new canonicalizeExistingPath() static method that returns realpathSync() for existing paths or falls back to path.resolve(), enabling canonical filesystem path resolution across the codebase.
Core Instruction & Template Loading src/core/artifact-graph/instruction-loader.ts	Updated loadTemplate() to canonicalize template paths on disk and improved error reporting; updated loadChangeContext() to canonicalize computed changeDir paths, ensuring consistent path handling downstream.
Artifact Output Resolution src/core/artifact-graph/outputs.ts	Modified resolveArtifactOutputs() to canonicalize both direct file paths and glob-matched results before deduplication and sorting, returning canonical filesystem paths instead of raw constructed paths.
Command Layer src/commands/workflow/instructions.ts, src/commands/workflow/templates.ts	Updated generateApplyInstructions() to use context.changeDir instead of deriving it; updated templatesCommand() to canonicalize computed template paths, establishing consistency with core loader behavior.
Test Updates test/core/artifact-graph/outputs.test.ts	Extended test assertions to expect canonical paths via realpathSync() for existing files; added new test case verifying canonical path resolution through symlinked directories.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• PR #443 — Modifies loadChangeContext() in instruction-loader.ts; this PR adds path canonicalization to the same function, creating a direct integration point.
• PR #410 — Introduces schema-directory resolution and instruction-loader proposals that this PR implements concretely through path canonicalization and context-driven changeDir handling.
• PR #422 — Also integrates context.changeDir into artifact instructions and path resolution; this PR aligns by canonicalizing the same changeDir values being passed through the system.

Suggested reviewers

• alfred-openspec

Poem

🐰 Paths were twisted, links were crossed,
Through symlinks lost, where realness was lost!
But a canonicalizer came hopping along—
Now every path sings the same true song,
From templates to changes, straight and strong! 🎯

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: canonicalize workflow artifact paths' accurately describes the main change—introducing path canonicalization throughout the workflow system to normalize artifact paths.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-windows-path-canonicalization

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}