Skip to content

feat: support native artifact downloads on macOS and Windows#103

Open
Waishnav wants to merge 6 commits into
mainfrom
feat/artifact-download-macos-windows
Open

feat: support native artifact downloads on macOS and Windows#103
Waishnav wants to merge 6 commits into
mainfrom
feat/artifact-download-macos-windows

Conversation

@Waishnav

@Waishnav Waishnav commented Jul 22, 2026

Copy link
Copy Markdown
Owner

Summary

  • add secure platform-specific artifact filesystem backends for Linux, macOS, and Windows
  • use descriptor-relative openat/mkdirat/linkat operations on macOS
  • pin Windows destination directories, reject reparse points and reserved paths, and preserve no-overwrite publication
  • extend the artifact tests and documentation across the three supported platforms

Verification

  • npm ci
  • npm run typecheck
  • npm test
  • npm run build
  • node dist/cli.js doctor

Summary by CodeRabbit

  • New Features
    • Native artifact downloads are supported on Linux, macOS, and Windows.
    • Downloads are published atomically and do not overwrite existing files.
  • Security
    • Strengthened “fail closed” safety checks with broader rejection of unsafe path forms (including symlink/junction/rparse behaviors, alternate data streams, device names, and ambiguous reserved segments).
    • POSIX downloads are written with mode 0600; Windows downloads inherit the destination directory’s ACL.
    • Partial downloads are verified before publication, with OS-specific stale-partial cleanup behavior.
  • Documentation
    • Updated artifact exchange, configuration, and security guidance to reflect the stricter validation and cross-platform semantics.

@coderabbitai

coderabbitai Bot commented Jul 22, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Native artifact downloads now use secure platform-specific filesystem targets for Linux, macOS, and Windows. The flow adds stricter destination validation, integrity checks, atomic publication, cleanup handling, platform tests, documentation updates, and the koffi runtime dependency.

Changes

Secure artifact downloads

Layer / File(s) Summary
Secure filesystem contracts and primitives
src/artifact-secure-filesystem.ts, src/artifact-secure-filesystem-common.ts
Defines the target lifecycle, platform dispatch, complete-write helpers, integrity verification, stale partial cleanup, and publication errors.
Native platform filesystem targets
src/artifact-secure-filesystem-linux.ts, src/artifact-secure-filesystem-darwin.ts, src/artifact-secure-filesystem-windows.ts, package.json
Adds Linux, Darwin, and Windows implementations using descriptor/path protection, libc bindings, pinned directory handles, exclusive partial files, verified publication, and cleanup.
Download integration and destination validation
src/artifact-tools.ts, src/artifact-download.test.ts, docs/*.md
Routes streaming downloads through secure targets, validates Windows-specific unsafe path segments, updates platform expectations and conditional tests, and documents cross-platform behavior and permission semantics.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant downloadIncomingArtifact
  participant openSecureArtifactTarget
  participant NativeArtifactTarget
  participant DestinationFilesystem

  downloadIncomingArtifact->>openSecureArtifactTarget: open workspace and destination target
  openSecureArtifactTarget->>NativeArtifactTarget: dispatch by platform
  downloadIncomingArtifact->>NativeArtifactTarget: writeAll(download chunks)
  downloadIncomingArtifact->>NativeArtifactTarget: syncAndVerify(expected size)
  NativeArtifactTarget->>DestinationFilesystem: publish verified partial without overwrite
  NativeArtifactTarget-->>downloadIncomingArtifact: publication result
  downloadIncomingArtifact->>NativeArtifactTarget: close and clean up resources
Loading

Possibly related PRs

  • Waishnav/devspace#88: Introduces the native artifact download flow that this PR refactors and extends.

Poem

I’m a rabbit with files tucked tight,
Across three lands they land just right.
No sly links leap, no paths mislead,
Checked, synced, and planted like seed.
Hop-hop—the partials clear the way!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 2.94% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
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.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title matches the main goal of adding native artifact download support, though it omits Linux which is also part of the change.
✨ 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 feat/artifact-download-macos-windows

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

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/artifact-secure-filesystem.ts (1)

3-5: 🩺 Stability & Availability | 🔵 Trivial | 🏗️ Heavy lift

Static imports pull koffi into every platform, including Linux.

openSecureArtifactTarget only needs one platform module at runtime, but the top-level imports of artifact-secure-filesystem-darwin.js and artifact-secure-filesystem-windows.js (both of which import koffi from "koffi") cause the native koffi addon to be resolved even on Linux, where the descriptor-based Linux backend never touches it. If koffi fails to load (missing prebuilt for an arch, install issue), the artifact feature breaks on Linux too. Consider loading the platform module lazily inside each branch.

♻️ Lazy per-platform loading
-import { openDarwinArtifactTarget } from "./artifact-secure-filesystem-darwin.js";
-import { openLinuxArtifactTarget } from "./artifact-secure-filesystem-linux.js";
-import { openWindowsArtifactTarget } from "./artifact-secure-filesystem-windows.js";
 export async function openSecureArtifactTarget(
   options: SecureArtifactTargetOptions,
 ): Promise<SecureArtifactTarget> {
-  if (process.platform === "linux") return openLinuxArtifactTarget(options);
-  if (process.platform === "darwin") return openDarwinArtifactTarget(options);
-  if (process.platform === "win32") return openWindowsArtifactTarget(options);
+  if (process.platform === "linux") {
+    return (await import("./artifact-secure-filesystem-linux.js")).openLinuxArtifactTarget(options);
+  }
+  if (process.platform === "darwin") {
+    return (await import("./artifact-secure-filesystem-darwin.js")).openDarwinArtifactTarget(options);
+  }
+  if (process.platform === "win32") {
+    return (await import("./artifact-secure-filesystem-windows.js")).openWindowsArtifactTarget(options);
+  }
   throw new ArtifactError(
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/artifact-secure-filesystem.ts` around lines 3 - 5, Update
openSecureArtifactTarget to remove the top-level platform imports and lazily
load only the selected backend module inside each platform branch. Ensure Linux
uses artifact-secure-filesystem-linux.js without resolving the Darwin or Windows
modules, and preserve the existing platform-specific target behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/artifact-secure-filesystem.ts`:
- Around line 3-5: Update openSecureArtifactTarget to remove the top-level
platform imports and lazily load only the selected backend module inside each
platform branch. Ensure Linux uses artifact-secure-filesystem-linux.js without
resolving the Darwin or Windows modules, and preserve the existing
platform-specific target behavior.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7d221925-6dbc-4901-b68a-aef19ab32c68

📥 Commits

Reviewing files that changed from the base of the PR and between 0d9b60c and ed2ae81.

⛔ Files ignored due to path filters (1)
  • package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (11)
  • docs/artifact-exchange.md
  • docs/configuration.md
  • docs/security.md
  • package.json
  • src/artifact-download.test.ts
  • src/artifact-secure-filesystem-common.ts
  • src/artifact-secure-filesystem-darwin.ts
  • src/artifact-secure-filesystem-linux.ts
  • src/artifact-secure-filesystem-windows.ts
  • src/artifact-secure-filesystem.ts
  • src/artifact-tools.ts

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant