Add optional OCI output artifacts

Support optional Acton output artifacts fetched from OCI repositories during
dependency resolution. Artifacts are keyed by source content hash, interface
version, and target tuple.

Use valid local cache entries before registry lookups and fall back to source
when no matching artifact is available.

Add artifact pack, push, and hash commands, local OCI layout support, tests,
and guide documentation.

Author: Kristian Larsson

compiler/acton/Main.hs

@@ -133,6 +133,7 @@ main = do
           C.CmdOpt gopts (C.PkgUpgrade opts) -> PkgCommands.pkgUpgradeCommand gopts opts
           C.CmdOpt gopts C.PkgUpdate         -> PkgCommands.pkgUpdateCommand gopts
           C.CmdOpt gopts (C.PkgSearch opts)  -> PkgCommands.pkgSearchCommand gopts opts
+          C.CmdOpt gopts (C.Artifact opts)   -> artifactCommand gopts opts
           C.CmdOpt gopts (C.BuildSpecCmd o)   -> buildSpecCommand o
           C.CmdOpt gopts (C.Cloud opts)       -> undefined
           C.CmdOpt gopts (C.Doc opts)         -> printDocs gopts opts
@@ -511,6 +512,24 @@ withProjectLockForGen gopts sched gen projDir action =
       withProjectLockNotice gopts projDir $
         whenCurrentGen sched gen action
 
+artifactCommand :: C.GlobalOptions -> C.ArtifactCommand -> IO ()
+artifactCommand gopts cmd =
+    case cmd of
+      C.ArtifactHash _ ->
+        PkgCommands.artifactCommand gopts cmd
+      _ -> do
+        let opts = defaultCompileOptions { C.skip_build = True }
+            sp = Source.diskSourceProvider
+        paths <- loadProjectPaths opts
+        let projDir = projPath paths
+        withProjectLockNotice gopts projDir $ do
+          unless (C.quiet gopts) $
+            putStrLn ("Building project in " ++ projDir)
+          srcFiles <- projectSourceFiles paths
+          compileFiles sp gopts opts srcFiles True
+          generateProjectDocIndex sp gopts opts paths srcFiles
+          PkgCommands.artifactCommand gopts cmd
+
 requireProjectLayout :: Paths -> IO ()
 requireProjectLayout paths = do
     exists <- doesDirectoryExist (srcDir paths)
@@ -929,7 +948,7 @@ runWatchFile gopts absFile sched runOnce = do
 fetchCommand :: C.GlobalOptions -> IO ()
 fetchCommand gopts = do
     paths <- loadProjectPaths defaultCompileOptions
-    res <- try (fetchDependencies gopts paths []) :: IO (Either ProjectError ())
+    res <- try (fetchDependencies gopts paths [] []) :: IO (Either ProjectError ())
     case res of
       Left (ProjectError msg) -> printErrorAndExit msg
       Right () ->
@@ -955,7 +974,7 @@ sigCommand gopts sigOpts = do
     rootProj <- normalizePathSafe (projPath paths)
     sysAbs <- normalizePathSafe (sysPath paths)
     withProjectLockNotice queryGopts rootProj $ do
-      fetchDependencies queryGopts paths depOverrides
+      fetchDependencies queryGopts paths depOverrides (C.artifact_repos opts)
       projMap <- discoverProjects queryGopts sysAbs rootProj depOverrides
       target <- resolveSigTarget opts paths rootProj projMap (C.sigTarget sigOpts)
       tyFile <- case target of

compiler/acton/PkgCommands.hs

@@ -7,6 +7,7 @@ module PkgCommands
   , pkgUpgradeCommand
   , pkgUpdateCommand
   , pkgSearchCommand
+  , artifactCommand
   , zigPkgAddCommand
   , zigPkgRemoveCommand
   , PackageEntry(..)
@@ -21,6 +22,7 @@ module PkgCommands
 
 import Prelude hiding (readFile, writeFile)
 
+import qualified Acton.Artifact as Artifact
 import qualified Acton.BuildSpec as BuildSpec
 import qualified Acton.CommandLineParser as C
 import Acton.Compile (loadBuildSpec, throwProjectError)
@@ -30,7 +32,7 @@ import Control.Concurrent (threadDelay)
 import Control.Monad (filterM, forM, forM_, unless, when)
 import Data.Char (isHexDigit, isSpace)
 import Data.Foldable (toList)
-import Data.List (dropWhileEnd, isPrefixOf, isSuffixOf, sortOn)
+import Data.List (dropWhileEnd, isPrefixOf, isSuffixOf, sort, sortOn)
 import Data.List.Split (splitOn)
 import Data.Maybe (isJust)
 import qualified Data.Map as M
@@ -44,11 +46,12 @@ import Network.HTTP.Client (Manager, Response, httpLbs, parseRequest, requestHea
 import Network.HTTP.Client.TLS (newTlsManager)
 import Network.HTTP.Types.Header (Header)
 import Network.HTTP.Types.Status (statusCode)
-import System.Directory (Permissions, canonicalizePath, copyFile, createDirectoryIfMissing, doesDirectoryExist, doesFileExist, doesPathExist, getCurrentDirectory, getHomeDirectory, getPermissions, listDirectory, removeFile, setPermissions)
+import System.Directory (Permissions, canonicalizePath, copyFile, copyFileWithMetadata, createDirectoryIfMissing, doesDirectoryExist, doesFileExist, doesPathExist, getCurrentDirectory, getHomeDirectory, getPermissions, listDirectory, makeAbsolute, pathIsSymbolicLink, removeFile, setPermissions)
 import System.Environment (getExecutablePath, lookupEnv)
 import System.Exit (ExitCode(..))
 import System.FilePath ((</>), takeDirectory)
 import System.IO (IOMode(ReadMode, WriteMode), hClose, hGetContents, hPutStr, hPutStrLn, hSetEncoding, openFile, stderr, utf8)
+import System.IO.Temp (withSystemTempDirectory)
 import System.Process (CreateProcess(cwd), proc, readCreateProcessWithExitCode)
 import qualified Text.Regex.TDFA as TDFA
 
@@ -303,6 +306,179 @@ pkgSearchCommand _ opts = do
       then putStrLn "No packages matched your search."
       else forM_ (sortOn pkgName matched) printPkg
 
+artifactCommand :: C.GlobalOptions -> C.ArtifactCommand -> IO ()
+artifactCommand gopts cmd =
+    case cmd of
+      C.ArtifactPack opts ->
+        packActonArtifact gopts (C.artifactPackOutput opts)
+      C.ArtifactPush opts ->
+        pushActonArtifact gopts opts
+      C.ArtifactHash opts ->
+        printActonArtifactHash (C.artifactHashSourcePath opts)
+
+packActonArtifact :: C.GlobalOptions -> String -> IO ()
+packActonArtifact gopts outputArg = do
+    sourceHash <- computeArtifactSourceHash "."
+    output <- packActonArtifactTo sourceHash outputArg
+    unless (C.quiet gopts) $
+      putStrLn ("Wrote Acton artifact " ++ output)
+
+pushActonArtifact :: C.GlobalOptions -> C.ArtifactPushOptions -> IO ()
+pushActonArtifact gopts opts = do
+    sourceHash <- computeArtifactSourceHash "."
+    ref0 <- resolveArtifactRef sourceHash
+                               (C.artifactPushRepoUrl opts)
+                               (C.artifactPushArtifactRepo opts)
+    ref <- absolutizeLocalArtifactRef ref0
+    withSystemTempDirectory "acton-artifact-push" $ \tmp -> do
+      let archive = tmp </> Artifact.artifactArchiveFile
+      _ <- packActonArtifactTo sourceHash archive
+      runProcessChecked (Just tmp) "oras"
+        (["push"]
+         ++ Artifact.ociRefOrasOptions ref
+         ++ [ "--artifact-type", Artifact.artifactType
+            , Artifact.ociRefOrasTarget ref
+            , Artifact.artifactArchiveFile ++ ":" ++ Artifact.artifactMediaType
+            ])
+      unless (C.quiet gopts) $
+        putStrLn ("Pushed Acton artifact " ++ ref)
+
+packActonArtifactTo :: String -> String -> IO FilePath
+packActonArtifactTo sourceHash outputArg = do
+    cwd <- getCurrentDirectory
+    let output0 = if null outputArg then "out" </> Artifact.artifactArchiveFile else outputArg
+    createDirectoryIfMissing True (takeDirectory output0)
+    withSystemTempDirectory "acton-artifact-pack" $ \tmp -> do
+      Artifact.writeManifest tmp (Artifact.expectedManifest sourceHash)
+      runProcessChecked Nothing "tar"
+        [ "-czf", output0
+        , "-C", tmp, Artifact.artifactManifestFile
+        , "-C", cwd, "Build.act", "out/types"
+        ]
+    return output0
+
+printActonArtifactHash :: String -> IO ()
+printActonArtifactHash source = do
+    h <- computeArtifactSourceHash source
+    putStrLn h
+
+computeArtifactSourceHash :: FilePath -> IO String
+computeArtifactSourceHash source = do
+    isDir <- doesDirectoryExist source
+    unless isDir $
+      throwProjectError ("ERROR: Artifact source hash expects a package directory: " ++ source)
+    zigExe <- getZigExe
+    withSystemTempDirectory "acton-artifact-source" $ \tmp -> do
+      let staged = tmp </> "source"
+      -- TODO(source-hash): Avoid staging a copied package tree here.
+      --
+      -- This copy is intentionally simple and conservative, but source hashing is
+      -- foundational identity machinery and should eventually be computed directly
+      -- from the package directory. The desired implementation is an Acton-owned
+      -- package hash walker that follows Zig's package hashing semantics exactly
+      -- rather than invoking `zig fetch` on a temporary copy.
+      --
+      -- Requirements for that replacement:
+      --
+      -- * Keep the source boundary independent of git or any other VCS.
+      -- * Preserve the current Acton package selection rules: include ordinary
+      --   package inputs, exclude local/generated state such as out/, build.zig,
+      --   build.zig.zon, lock files, VCS dirs, caches, and artifact files.
+      -- * Match Zig's path normalization, directory ordering, file metadata/mode
+      --   treatment, digest algorithm, and final package-hash text encoding.
+      -- * Keep symlink behavior explicit. Today symlinks are rejected rather than
+      --   guessed; any future support must match Zig and have test coverage.
+      -- * Add stable fixture tests that compare Acton's in-place implementation
+      --   with `zig fetch` for representative package trees before switching over.
+      --
+      -- Until then, copying to a clean temp directory keeps generated build output
+      -- out of the hash while delegating the actual hash algorithm to Zig.
+      copyCanonicalSource source staged
+      requireRightWith "ERROR: Failed to compute source hash: " =<< zigFetchHash zigExe staged
+
+copyCanonicalSource :: FilePath -> FilePath -> IO ()
+copyCanonicalSource src dst =
+    copyCanonicalSourceAt [] src dst
+
+copyCanonicalSourceAt :: [FilePath] -> FilePath -> FilePath -> IO ()
+copyCanonicalSourceAt rel src dst = do
+    createDirectoryIfMissing True dst
+    entries <- sort <$> listDirectory src
+    forM_ entries $ \entry ->
+      let rel' = rel ++ [entry]
+      in unless (skipLocalSourceEntry rel') $ do
+        let srcEntry = src </> entry
+            dstEntry = dst </> entry
+        isSymlink <- pathIsSymbolicLink srcEntry
+        when isSymlink $
+          throwProjectError ("ERROR: Artifact source hash does not support symbolic links: " ++ srcEntry)
+        isDir <- doesDirectoryExist srcEntry
+        if isDir
+          then copyCanonicalSourceAt rel' srcEntry dstEntry
+          else do
+            createDirectoryIfMissing True (takeDirectory dstEntry)
+            copyFileWithMetadata srcEntry dstEntry
+
+skipLocalSourceEntry :: [FilePath] -> Bool
+skipLocalSourceEntry [] = False
+skipLocalSourceEntry rel =
+    entry `elem`
+      [ ".git"
+      , ".hg"
+      , ".svn"
+      , ".DS_Store"
+      , ".zig-cache"
+      , "zig-cache"
+      ] ||
+    rel `elem`
+      [ [".acton.lock"]
+      , [".acton.compile.lock"]
+      , [".acton"]
+      , [".acton.cache"]
+      , [".actonc.lock"]
+      , [".build"]
+      , ["out"]
+      , ["build.zig"]
+      , ["build.zig.zon"]
+      , [Artifact.artifactManifestFile]
+      , [Artifact.artifactArchiveFile]
+      ]
+  where
+    entry = last rel
+
+absolutizeLocalArtifactRef :: String -> IO String
+absolutizeLocalArtifactRef ref
+  | Artifact.ociRefIsLocal ref =
+      case splitLocalOciTarget (Artifact.ociRefOrasTarget ref) of
+        Just (path, tag) -> do
+          path' <- makeAbsolute path
+          return ("oci-layout://" ++ path' ++ ":" ++ tag)
+        Nothing -> return ref
+  | otherwise = return ref
+
+splitLocalOciTarget :: String -> Maybe (FilePath, String)
+splitLocalOciTarget target =
+    case break (== ':') (reverse target) of
+      (revTag, ':' : revPath)
+        | not (null revTag) && not (null revPath) ->
+            Just (reverse revPath, reverse revTag)
+      _ -> Nothing
+
+resolveArtifactRef :: String -> String -> String -> IO String
+resolveArtifactRef sourceHash repoUrl artifactRepo
+  | not (null artifactRepo) =
+      case Artifact.ociRefForRepository artifactRepo sourceHash of
+        Just ref -> return ref
+        Nothing ->
+          throwProjectError ("ERROR: Invalid OCI artifact repository " ++ artifactRepo)
+  | not (null repoUrl) =
+      case Artifact.deriveOciRef repoUrl sourceHash of
+        Just ref -> return ref
+        Nothing ->
+          throwProjectError ("ERROR: Could not derive OCI artifact ref from " ++ repoUrl)
+  | otherwise =
+      throwProjectError "ERROR: Specify --artifact-repo or --repo-url for artifact push"
+
 zigPkgAddCommand :: C.GlobalOptions -> C.ZigPkgAddOptions -> IO ()
 zigPkgAddCommand _ opts = do
     let depName = C.zigPkgAddName opts

compiler/acton/test.hs

@@ -450,6 +450,24 @@ parseFlagTests =
           assertBool "serial parser flag should be set" (C.parse_serial (C.buildCompile buildOpts))
         _ ->
           assertFailure "expected build command"
+  , testCase "build parser accepts artifact repositories" $ do
+      parsed <- parseArgs ["build", "--artifact-repo", "local-registry.local-domain.com/acton-out"]
+      case parsed of
+        C.CmdOpt _ (C.Build buildOpts) ->
+          assertEqual "artifact repos"
+            ["local-registry.local-domain.com/acton-out"]
+            (C.artifact_repos (C.buildCompile buildOpts))
+        _ ->
+          assertFailure "expected build command"
+  , testCase "artifact parser accepts top-level push command" $ do
+    parsed <- parseArgs ["artifact", "push", "--artifact-repo", "registry.local/acton-out"]
+    case parsed of
+      C.CmdOpt _ (C.Artifact (C.ArtifactPush opts)) -> do
+        assertEqual "artifact repo" "registry.local/acton-out" (C.artifactPushArtifactRepo opts)
+      _ ->
+        assertFailure "expected artifact push command"
+  , testCase "artifact parser rejects raw push refs" $ do
+      assertParseFails ["artifact", "push", "--ref", "registry.local/acton-out:anything"]
   , testCase "build parser help includes --release alias" $ do
       helpText <- renderParserHelp ["build", "--help"]
       assertBool "help text should include --release" ("--release" `isInfixOf` helpText)
@@ -718,6 +736,13 @@ parseFlagTests =
         OA.CompletionInvoked _ ->
           assertFailure ("parser requested shell completion for " ++ unwords args)
 
+    assertParseFails args =
+      case OA.execParserPure OA.defaultPrefs parserInfo args of
+        OA.Failure _ -> return ()
+        OA.Success _ -> assertFailure ("parser unexpectedly accepted " ++ unwords args)
+        OA.CompletionInvoked _ ->
+          assertFailure ("parser requested shell completion for " ++ unwords args)
+
     assertParsedBuildOptimize args expected = do
       parsed <- parseArgs args
       case parsed of
@@ -1004,8 +1029,10 @@ actonProjTests =
           let srcDir = proj </> "src"
               buildAct = proj </> "Build.act"
               mainAct = srcDir </> "main.act"
+              artifactDep = proj </> "deps" </> "artifact_dep"
           createDirectoryIfMissing True srcDir
           createDirectoryIfMissing True (proj </> "deps")
+          createDirectoryIfMissing True (artifactDep </> "out" </> "types")
           writeFile buildAct $ unlines
             [ "name = \"invalid_dep_override\""
             , "fingerprint = 0xb33bef4512345678"
@@ -1019,12 +1046,36 @@ actonProjTests =
             , "    print(\"hello\")"
             , "    env.exit(0)"
             ]
+          writeFile (artifactDep </> "Build.act") $ unlines
+            [ "name = \"artifact_dep\""
+            , "fingerprint = 0xa44bef4512345678"
+            , "dependencies = {}"
+            , "zig_dependencies = {}"
+            ]
+          writeFile (artifactDep </> "acton-artifact.json") "{}"
           actonExe <- canonicalizePath "../../dist/bin/acton"
           (returnCode, _cmdOut, cmdErr) <- readCreateProcessWithExitCode (proc actonExe ["build", "--dep", "dep_a=deps"]){ cwd = Just proj } ""
           assertEqual "acton should fail for invalid --dep path" (ExitFailure 1) returnCode
           assertBool "error should mention bad dependency path" ("Dependency dep_a path is not an Acton project root" `isInfixOf` cmdErr)
           assertBool "error should mention required project files" ("Build.act" `isInfixOf` cmdErr)
           assertBool "error should mention src requirement" ("src/" `isInfixOf` cmdErr)
+          (artifactReturnCode, _artifactOut, artifactErr) <- readCreateProcessWithExitCode
+            (proc actonExe ["build", "--dep", "dep_a=deps/artifact_dep"]){ cwd = Just proj } ""
+          assertEqual "acton should reject artifact roots as --dep paths" (ExitFailure 1) artifactReturnCode
+          assertBool "artifact root should still be rejected as a local source dep"
+            ("Dependency dep_a path is not an Acton project root" `isInfixOf` artifactErr)
+          writeFile buildAct $ unlines
+            [ "name = \"invalid_dep_override\""
+            , "fingerprint = 0xb33bef4512345678"
+            , ""
+            , "dependencies = {"
+            , "  \"dep_a\": (path=\"deps/artifact_dep\")"
+            , "}"
+            ]
+          (pathReturnCode, _pathOut, pathErr) <- readCreateProcessWithExitCode (proc actonExe ["build"]){ cwd = Just proj } ""
+          assertEqual "acton should reject artifact roots as Build.act paths" (ExitFailure 1) pathReturnCode
+          assertBool "path error should point users to artifact repos"
+            ("Use --artifact-repo to search output artifacts" `isInfixOf` pathErr)
 
   -- Verify pruning keeps binaries for modules that still have roots across build / test runs.
   , testCase "executable pruning" $ do

compiler/lib/package.yaml.in

@@ -61,6 +61,7 @@ dependencies:
 library:
   source-dirs: src
   exposed-modules:
+    - Acton.Artifact
     - Acton.Boxing
     - Acton.BuildSpec
     - Acton.Builtin