fix(server): GET /api/workflows/:name now resolves global (~/.archon/workflows/) workflows

[marciotoze]

Problem

The workflow builder (/workflows/builder?edit=<name>) and any direct fetch of a single workflow by name return 404 for global workflows placed in ~/.archon/workflows/.

The GET /api/workflows/:name handler looked in two places only:

1. <cwd>/.archon/workflows/<name>.yaml (project)
2. Bundled defaults (embedded map / filesystem)

It never checked ~/.archon/workflows/, so opening a global workflow in the builder always failed silently.

This is complementary to #1257 (which fixes GET /api/workflows list + command-handler), but that PR does not touch the single-fetch endpoint — users whose workflows appear in the list still can't open them in the builder.

Fix

Add a second lookup step between project and bundled that reads from getHomeWorkflowsPath() (~/.archon/workflows/), matching the three-tier priority already enforced by discoverWorkflowsWithConfig:

bundled < global < project

Files changed:

File	Change
packages/server/src/routes/api.ts	Import getHomeWorkflowsPath; add global lookup step in GET /api/workflows/:name
packages/server/src/routes/api.workflows.test.ts	3 new tests covering global source, priority over bundled, and project priority over global

Tests

30 pass, 0 fail

Three new test cases in describe('GET /api/workflows/:name'):

• source:'global' — workflow in ~/.archon/workflows/ is found and returned with correct source
• Global overrides bundled — a global workflow shadows a bundled default of the same name
• Project beats global — project workflow takes priority when cwd is provided

Validation

bun run validate  # type-check ✅  lint ✅  format ✅  tests ✅

Linked issue

#1138 (complementary path — single-fetch endpoint not covered by #1257)

Summary by CodeRabbit

• New Features

  • Workflows placed in a global user directory are now discovered at runtime; resolution order is: project workflows → global workflows (including one-level subdirectories) → bundled defaults.

• Tests

  • Added integration tests validating global and project workflow resolution, one-level subdirectory discovery, override behavior, and endpoint responses for each source.

[coderabbitai]

📝 Walkthrough

Walkthrough

The GET /api/workflows/:name handler now checks a home-scoped global workflows directory (ARCHON_HOME) (direct files and one-level subdirs) between project and bundled fallbacks; valid global YAML returns source: "global", parse errors return HTTP 500, and ENOENT filesystem misses are ignored to continue lookup.

Changes

Cohort / File(s)	Summary
Server route: global workflow lookup packages/server/src/routes/api.ts	Insert home-scoped global workflow resolution using getHomeWorkflowsPath(); iterate candidates (direct + one-level subdirs), parse with parseWorkflow, return source: "global" on success; treat parse errors as HTTP 500; ignore ENOENT when scanning candidates.
Integration tests: workflow resolution packages/server/src/routes/api.workflows.test.ts	Add tests using temporary ARCHON_HOME fixtures asserting: direct global file loading, global in one-level subdir, global overriding bundled, project taking precedence over global, with setup/cleanup and mocked cwd.
Misc (no public API changes) packages/server/...	No exported/public declarations changed; internal behavior and tests updated.

Sequence Diagram(s)

sequenceDiagram
    rect rgba(200,230,255,0.5)
    participant Client
    end
    rect rgba(220,255,200,0.5)
    participant Server
    end
    rect rgba(255,240,200,0.5)
    participant FS as "Filesystem (Project / ARCHON_HOME)"
    end
    rect rgba(240,220,255,0.5)
    participant Bundled as "Bundled Workflows"
    end

    Client->>Server: GET /api/workflows/:name
    Server->>FS: check project .archon/workflows/:name.yaml
    alt project file found & valid
        FS-->>Server: file contents
        Server->>Client: 200 { source: "project", workflow }
    else
        Server->>FS: iterate ARCHON_HOME/workflows candidates (direct + 1-level subdirs)
        alt global file found
            FS-->>Server: file contents
            alt parse succeeds
                Server->>Client: 200 { source: "global", filename, workflow }
            else parse fails
                Server->>Client: 500 { error: "Global workflow file is invalid ..." }
            end
        else no global found
            Server->>Bundled: load default workflow
            Bundled-->>Server: bundled workflow
            Server->>Client: 200 { source: "bundled", workflow }
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• #1138: Addresses missing home/global workflow discovery in GET /api/workflows — this PR implements explicit ARCHON_HOME scanning that overlaps the issue's objective.

Possibly related PRs

• #1315: Adds server-side home/global workflow resolution and source: "global" semantics similar to the changes introduced here.

Poem

🐰
I hop through home and project lanes to peep,
Sniff YAML crumbs where workflows sleep,
If global gleams I trumpet "found" so bold,
If broken, thump — a 500 told,
Bundled nests keep me cozy when cold.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding support for resolving global workflows in the GET /api/workflows/:name handler.
Description check	✅ Passed	The PR description covers most required sections including problem, fix, tests, and validation, though some template sections like Architecture Diagram and detailed Side Effects are missing.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/server/src/routes/api.ts`:
- Around line 2264-2284: The global workflow lookup only checks
join(getHomeWorkflowsPath(), filename) and must also probe one-level subfolders
like join(getHomeWorkflowsPath(), folder, filename) to mirror discovery; update
the block that reads globalFilePath (and its error handling that uses
parseWorkflow, apiError, getLog().error and workflow.fetch_global_failed) to
first try the direct path and if missing iterate the immediate child directories
under getHomeWorkflowsPath() to look for filename, parse and return the workflow
with source: 'global' when found (or alternatively delegate to the shared
workflow resolver if available) before falling back to bundled defaults.

In `@packages/server/src/routes/api.workflows.test.ts`:
- Around line 256-343: Each test that sets process.env.ARCHON_HOME (the three
tests named "returns global workflow with source:global when file exists in
~/.archon/workflows/", "global workflow takes priority over bundled defaults",
and "project workflow takes priority over global workflow") should capture the
original value before mutating it and restore it in the finally block instead of
simply deleting it; specifically, store const previousArchonHome =
process.env.ARCHON_HOME before assigning process.env.ARCHON_HOME =
testArchonHome, and in each finally block restore by setting
process.env.ARCHON_HOME = previousArchonHome if it was defined or delete
process.env.ARCHON_HOME if previousArchonHome is undefined, keeping the existing
cleanup of test directories (testArchonHome/testProjectDir) unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6142d8fd-6983-47b7-9b14-1d73975be5a4

📥 Commits

Reviewing files that changed from the base of the PR and between b99cee4 and ca07ca6.

📒 Files selected for processing (2)

• packages/server/src/routes/api.ts
• packages/server/src/routes/api.workflows.test.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/server/src/routes/api.ts`:
- Around line 2268-2281: The broad try/catch around readdir and the inner
try/catch around stat currently swallow all filesystem errors; change both to
inspect the caught Error (use err.code) and only ignore ENOENT (directory/not
found) while rethrowing any other errors (e.g., EACCES, EPERM, ENOTDIR) so they
surface; specifically update the outer block around readdir(globalBase) and the
inner block around stat(entryPath) that populate globalCandidates (referencing
globalBase, globalCandidates, filename, entryPath, readdir, stat) to check
error.code === 'ENOENT' and continue/return safely for that case, but throw the
original error for all other codes and add a brief comment explaining the
intentional ENOENT fallback.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c5a5b40c-b69b-4a5d-a43b-f6fd9868be1a

📥 Commits

Reviewing files that changed from the base of the PR and between ca07ca6 and 7b554bb.

📒 Files selected for processing (2)

• packages/server/src/routes/api.ts
• packages/server/src/routes/api.workflows.test.ts

[coderabbitai]

🧹 Nitpick comments (1)

packages/server/src/routes/api.ts (1)

2264-2308: Global lookup logic is correct — optional efficiency tweak available.

Priority ordering (bundled < global < project), 1-level subfolder support, ENOENT-only swallowing with clear inline comments, and the source: 'global' label all match discovery semantics. Past concerns (subfolder support, silent error swallowing) are addressed.

One optional refactor: readdir with withFileTypes: true removes the per-entry stat round-trip and collapses the inner try/catch, since Dirent.isDirectory() doesn't fail mid-iteration the way a separate stat call can race against the entry being deleted.

♻️ Optional refactor

-      const entries = await readdir(globalBase);
-      for (const entry of entries) {
-        const entryPath = join(globalBase, entry);
-        try {
-          const entryStat = await stat(entryPath);
-          if (entryStat.isDirectory()) globalCandidates.push(join(entryPath, filename));
-        } catch (err) {
-          if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-            getLog().error({ err, entryPath, name }, 'workflow.global_entry_stat_failed');
-            return apiError(c, 500, 'Failed to inspect global workflow directory');
-          }
-          // Entry disappeared between readdir and stat — safe to skip.
-        }
-      }
+      const entries = await readdir(globalBase, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          globalCandidates.push(join(globalBase, entry.name, filename));
+        }
+      }

If you keep this change, the stat import on line 9 becomes unused.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/server/src/routes/api.ts` around lines 2264 - 2308, Replace the
per-entry stat round-trip in the global workflow discovery loop by calling
readdir(globalBase, { withFileTypes: true }) and use Dirent.isDirectory() to
detect subfolders (update the loop that builds globalCandidates from
globalBase/entries), removing the inner try/catch around stat/entryPath and
eliminating the entryStat/entryPath variables; also remove the now-unused stat
import if it becomes unused. Ensure the outer ENOENT handling for readdir stays
the same and keep the subsequent readFile/parseWorkflow logic untouched.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/server/src/routes/api.ts`:
- Around line 2264-2308: Replace the per-entry stat round-trip in the global
workflow discovery loop by calling readdir(globalBase, { withFileTypes: true })
and use Dirent.isDirectory() to detect subfolders (update the loop that builds
globalCandidates from globalBase/entries), removing the inner try/catch around
stat/entryPath and eliminating the entryStat/entryPath variables; also remove
the now-unused stat import if it becomes unused. Ensure the outer ENOENT
handling for readdir stays the same and keep the subsequent
readFile/parseWorkflow logic untouched.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dc3ee12b-2712-4be3-91d6-928b671c4326

📥 Commits

Reviewing files that changed from the base of the PR and between 7b554bb and 65473ac.

📒 Files selected for processing (1)

• packages/server/src/routes/api.ts

[Wirasm]

Hi @marciotoze — thanks for opening this PR.

This repository uses a PR template at .github/pull_request_template.md with several required sections. A few of them appear to be empty or placeholder here:

• Summary
• UX Journey
• Architecture Diagram
• Label Snapshot
• Change Metadata
• Security Impact
• Compatibility / Migration
• Human Verification
• Side Effects / Blast Radius
• Rollback Plan
• Risks and Mitigations

Could you fill those out (even briefly)? The template helps reviewers understand scope, risk, and rollback — it speeds up review significantly.

If a section genuinely doesn't apply, just write "N/A" in it rather than leaving it blank.

[Wirasm]

@marciotoze related to #1138 — overlapping area or partial fix.